SDK de Android - Referencia de métodos
Esta referencia integral documenta todos los métodos disponibles en el Singular SDK para aplicaciones Android. El SDK ofrece funcionalidad para inicialización, tracking de eventos, reporte de ingresos, atribución, cumplimiento de privacidad de datos y configuración. Cada método se presenta con una descripción, una firma y ejemplos prácticos de uso para ayudar a los desarrolladores a integrar las capacidades del Singular SDK en sus aplicaciones.
adRevenue
Método Singular.adRevenue
Trackea eventos de ingresos por publicidad con información detallada de los datos del anuncio. Este método le permite reportar los ingresos generados por los anuncios mostrados en su aplicación.
Firma
public static void adRevenue(SingularAdData adData);
Ejemplo de uso
// Create ad data object
val adData = SingularAdData("AdMob", "USD", 0.05).apply {
withAdUnitId("ca-app-pub-123456789/1234567890")
withAdType("Rewarded")
withAdPlacementName("level_complete")
}
// Track ad revenue event
Singular.adRevenue(adData)
// Create ad data object
SingularAdData adData = new SingularAdData("AdMob", "USD", 0.05)
.withAdUnitId("ca-app-pub-123456789/1234567890")
.withAdType("Rewarded")
.withAdPlacementName("level_complete");
// Track ad revenue event
Singular.adRevenue(adData);
clearGlobalProperties
Método Singular.clearGlobalProperties
Elimina todas las propiedades globales configuradas anteriormente. Es útil cuando necesita restablecer las propiedades globales, por ejemplo cuando un usuario cierra sesión en su aplicación.
Firma
public static void clearGlobalProperties();
Ejemplo de uso
// Clear all global properties
Singular.clearGlobalProperties()
// Clear all global properties
Singular.clearGlobalProperties();
createReferrerShortLink
Método Singular.createReferrerShortLink
Crea un enlace corto con información de referente que puede usarse para compartir y atribución. Este método genera enlaces trackeables que pueden compartirse con los usuarios, permitiéndole atribuir instalaciones y actividades a fuentes de referencia específicas.
Firma
public static void createReferrerShortLink(String baseLink, String referrerName, String referrerId,
JSONObject passthroughParams, ShortLinkHandler shortLinkHandler);
Ejemplo de uso
// Create a short link for referral
val passthroughParams = JSONObject().apply {
put("channel", "sms")
put("campaign", "summer_promo")
}
Singular.createReferrerShortLink(
"https://sample.sng.link/B4tbm/v8fp",
"John Doe",
"aq239897",
passthroughParams,
object : ShortLinkHandler {
override fun onSuccess(link: String) {
println("Generated short link: $link")
// Share the link with users
}
override fun onError(error: String) {
println("Error creating short link: $error")
}
}
)
// Create a short link for referral
try {
JSONObject passthroughParams = new JSONObject();
passthroughParams.put("channel", "sms");
passthroughParams.put("campaign", "summer_promo");
Singular.createReferrerShortLink(
"https://sample.sng.link/B4tbm/v8fp",
"John Doe",
"aq239897",
passthroughParams,
new ShortLinkHandler() {
@Override
public void onSuccess(String link) {
System.out.println("Generated short link: " + link);
// Share the link with users
}
@Override
public void onError(String error) {
System.out.println("Error creating short link: " + error);
}
}
);
} catch (JSONException e) {
e.printStackTrace();
}
customRevenue
Métodos Singular.customRevenue
Trackea eventos de ingresos personalizados con un nombre de evento, moneda, monto e información opcional del producto. Esto permite un tracking de ingresos más específico con nombres de eventos personalizados.
Al pasar un objeto
purchase, el SDK solo extrae los detalles de recibo, firma y SKU si es una instancia de
com.android.billingclient.api.Purchase. Otros tipos recurren a un evento de ingresos básico solo con moneda y monto.
Firmas
public static boolean customRevenue(String eventName, String currency, double amount, Object purchase);
public static boolean customRevenue(String eventName, String currency, double amount, Object purchase,
Map<String, Object> attributes);
public static boolean customRevenue(String eventName, String currency, double amount);
public static boolean customRevenue(String eventName, String currency, double amount,
Map<String, Object> attributes);
public static boolean customRevenue(String eventName, String currency, double amount,
String receipt, String receiptSignature);
public static boolean customRevenue(String eventName, String currency, double amount, String productSKU,
String productName, String productCategory, int productQuantity,
double productPrice);
public static boolean customRevenue(String eventName, JSONObject json);
Ejemplo de uso
// Track a custom revenue event
Singular.customRevenue("premium_subscription", "USD", 9.99)
// Track a custom revenue event with attributes
val attributes = mapOf(
"product_id" to "com.app.gems_pack_small",
"quantity" to 1
)
Singular.customRevenue("in_app_purchase", "USD", 5.99, attributes)
// Track a custom revenue event from a pre-built JSON payload
val customRevenueJson = JSONObject().apply {
put("currency", "USD")
put("amount", 5.99)
put("product_id", "com.app.gems_pack_small")
}
Singular.customRevenue("in_app_purchase", customRevenueJson)
// Track a custom revenue event
Singular.customRevenue("premium_subscription", "USD", 9.99);
// Track a custom revenue event with attributes
Map<String, Object> attributes = new HashMap<>();
attributes.put("product_id", "com.app.gems_pack_small");
attributes.put("quantity", 1);
Singular.customRevenue("in_app_purchase", "USD", 5.99, attributes);
// Track a custom revenue event from a pre-built JSON payload
try {
JSONObject customRevenueJson = new JSONObject();
customRevenueJson.put("currency", "USD");
customRevenueJson.put("amount", 5.99);
customRevenueJson.put("product_id", "com.app.gems_pack_small");
Singular.customRevenue("in_app_purchase", customRevenueJson);
} catch (JSONException e) {
e.printStackTrace();
}
event
Métodos Singular.event
Trackea eventos con el nombre especificado y atributos personalizados opcionales. Use estos métodos para trackear acciones del usuario y engagement dentro de su aplicación.
La sobrecarga con varargs espera pares clave/valor, por lo que
args debe contener un número par de elementos. Una cantidad impar provoca que la llamada devuelva
false sin enviar el evento.
Firmas
public static boolean event(String name);
public static boolean event(String name, String extra);
public static boolean event(String name, Object... args);
Ejemplo de uso
// Track a simple event
Singular.event("level_completed")
// Track an event with variable arguments
Singular.event("level_completed",
"level_id", 5,
"score", 12500,
"time_spent", 120,
"difficulty", "medium"
)
// Track a simple event
Singular.event("level_completed");
// Track an event with variable arguments
Singular.event("level_completed",
"level_id", 5,
"score", 12500,
"time_spent", 120,
"difficulty", "medium"
);
eventJSON
Método Singular.eventJSON
Trackea eventos con un objeto JSON que contiene atributos personalizados. Este método proporciona mayor flexibilidad para estructuras de datos de eventos complejas.
Firma
public static boolean eventJSON(String name, final JSONObject json);
Ejemplo de uso
// Track an event with JSON object
val eventData = JSONObject().apply {
put("level_id", 5)
put("score", 12500)
put("time_spent", 120)
put("difficulty", "medium")
}
Singular.eventJSON("level_completed", eventData)
// Track an event with JSON object
try {
JSONObject eventData = new JSONObject();
eventData.put("level_id", 5);
eventData.put("score", 12500);
eventData.put("time_spent", 120);
eventData.put("difficulty", "medium");
Singular.eventJSON("level_completed", eventData);
} catch (JSONException e) {
e.printStackTrace();
}
getGlobalProperties
Método Singular.getGlobalProperties
Recupera todas las propiedades globales actualmente configuradas. Este método devuelve un mapa que contiene todas las propiedades globales que se han configurado para el SDK.
Firma
public static Map<String, String> getGlobalProperties();
Ejemplo de uso
// Get all global properties
val properties = Singular.getGlobalProperties()
println("Global properties: $properties")
// Get all global properties
Map<String, String> properties = Singular.getGlobalProperties();
System.out.println("Global properties: " + properties);
getLimitDataSharing
Método Singular.getLimitDataSharing
Recupera el estado actual de la limitación de uso compartido de datos. Este método devuelve un booleano que indica si el uso compartido de datos está actualmente limitado.
Devuelve
false si el SDK no se ha inicializado, independientemente de cualquier valor configurado previamente mediante
SingularConfig.withLimitDataSharing. Siempre interprete
false en contexto, no como prueba de que el usuario optó por participar.
Firma
public static boolean getLimitDataSharing();
Ejemplo de uso
// Check if data sharing is limited
val isLimited = Singular.getLimitDataSharing()
if (isLimited) {
println("Data sharing is currently limited")
}
// Check if data sharing is limited
boolean isLimited = Singular.getLimitDataSharing();
if (isLimited) {
System.out.println("Data sharing is currently limited");
}
getSessionId
Método Singular.getSessionId
Devuelve el ID de sesión actual. Puede usarse para rastrear y correlacionar eventos dentro de la misma sesión.
Devuelve
Constants.INVALID si el SDK no se ha inicializado. Llame siempre a
Singular.init() antes de depender de este valor.
Firma
public static long getSessionId();
Ejemplo de uso
// Get the current session ID
val sessionId = Singular.getSessionId()
println("Current session ID: $sessionId")
// Get the current session ID
long sessionId = Singular.getSessionId();
System.out.println("Current session ID: " + sessionId);
init
Método Singular.init
Inicializa el Singular SDK con la clave API y el secreto proporcionados, o con un objeto de configuración. Este es el primer método que debe llamar para comenzar a usar el Singular SDK.
Firmas
public static boolean init(final Context context, final String apiKey, final String secret);
public static boolean init(final Context context, final SingularConfig config);
Ejemplo de uso
// Simple initialization with API key and secret
Singular.init(context, "SDK KEY", "YOUR_SECRET")
// Initialize with configuration object
val config = SingularConfig("SDK KEY", "YOUR_SECRET")
.withCustomUserId("user_123456")
.withSessionTimeoutInSec(60)
Singular.init(context, config)
// Simple initialization with API key and secret
Singular.init(context, "SDK KEY", "YOUR_SECRET");
// Initialize with configuration object
SingularConfig config = new SingularConfig("SDK KEY", "YOUR_SECRET")
.withCustomUserId("user_123456")
.withSessionTimeoutInSec(60);
Singular.init(context, config);
isAllTrackingStopped
Método Singular.isAllTrackingStopped
Verifica si todo el tracking está actualmente detenido. Este método devuelve un booleano que indica si el tracking está actualmente detenido.
Devuelve
false si el SDK no se ha inicializado. Trate
false como "no detenido o no inicializado", no como "trackeando activamente".
Firma
public static boolean isAllTrackingStopped();
Ejemplo de uso
// Check if tracking is stopped
if (Singular.isAllTrackingStopped()) {
println("Tracking is currently stopped")
}
// Check if tracking is stopped
if (Singular.isAllTrackingStopped()) {
System.out.println("Tracking is currently stopped");
}
limitDataSharing
Método Singular.limitDataSharing
Establece el estado de limitación de uso compartido de datos. Utilice este método para limitar el uso compartido de datos según el consentimiento del usuario o los requisitos de privacidad.
Firma
public static void limitDataSharing(boolean shouldLimitDataSharing);
Ejemplo de uso
// To limit data sharing (e.g., when user opts out)
Singular.limitDataSharing(true)
// To enable full data sharing (e.g., when user opts in)
Singular.limitDataSharing(false)
// To limit data sharing (e.g., when user opts out)
Singular.limitDataSharing(true);
// To enable full data sharing (e.g., when user opts in)
Singular.limitDataSharing(false);
onActivityPaused
Método Singular.onActivityPaused
Notifica al SDK cuando una actividad se pausa. Esto debe llamarse desde el método onPause() de sus actividades para rastrear el ciclo de vida de la sesión.
Firma
public static void onActivityPaused();
Ejemplo de uso
override fun onPause() {
super.onPause()
Singular.onActivityPaused()
}
@Override
protected void onPause() {
super.onPause();
Singular.onActivityPaused();
}
onActivityResumed
Método Singular.onActivityResumed
Notifica al SDK cuando una actividad se reanuda. Esto debe llamarse desde el método onResume() de sus actividades para rastrear el ciclo de vida de la sesión.
Firma
public static void onActivityResumed();
Ejemplo de uso
override fun onResume() {
super.onResume()
Singular.onActivityResumed()
}
@Override
protected void onResume() {
super.onResume();
Singular.onActivityResumed();
}
resumeAllTracking
Método Singular.resumeAllTracking
Reanuda todas las actividades de tracking que se detuvieron previamente. Use este método para volver a habilitar el tracking después de que se haya detenido.
Firma
public static void resumeAllTracking();
Ejemplo de uso
// Resume tracking when user opts back in
Singular.resumeAllTracking()
// Resume tracking when user opts back in
Singular.resumeAllTracking();
revenue
Métodos Singular.revenue
Trackea eventos de ingresos con varios parámetros, incluidos la moneda, el monto y los detalles del producto. Esto permite un tracking integral de ingresos para su aplicación.
Al pasar un objeto
purchase, el SDK solo extrae los detalles de recibo, firma y SKU si es una instancia de
com.android.billingclient.api.Purchase. Otros tipos recurren a un evento de ingresos básico solo con moneda y monto.
Firmas
public static boolean revenue(String currency, double amount, Object purchase);
public static boolean revenue(String currency, double amount, Object purchase, Map<String, Object> attributes);
public static boolean revenue(String currency, double amount);
public static boolean revenue(String currency, double amount, Map<String, Object> attributes);
public static boolean revenue(String currency, double amount, String receipt, String receiptSignature);
public static boolean revenue(String currency, double amount, String productSKU, String productName,
String productCategory, int productQuantity, double productPrice);
public static boolean revenue(JSONObject json);
Ejemplo de uso
// Track revenue with currency and amount
Singular.revenue("USD", 9.99)
// Track revenue with additional attributes
val attributes = mapOf(
"product_id" to "premium_gems",
"quantity" to 2
)
Singular.revenue("USD", 19.98, attributes)
// Track revenue with Google Play purchase object
Singular.revenue("USD", 9.99, purchase)
// Track revenue with detailed product information
Singular.revenue("USD", 19.98,
"SKU123456",
"Premium Sword",
"Weapons",
2,
9.99
)
// Track revenue from a pre-built JSON payload
val revenueJson = JSONObject().apply {
put("currency", "USD")
put("amount", 9.99)
put("product_id", "premium_gems")
}
Singular.revenue(revenueJson)
// Track revenue with currency and amount
Singular.revenue("USD", 9.99);
// Track revenue with additional attributes
Map<String, Object> attributes = new HashMap<>();
attributes.put("product_id", "premium_gems");
attributes.put("quantity", 2);
Singular.revenue("USD", 19.98, attributes);
// Track revenue with Google Play purchase object
Singular.revenue("USD", 9.99, purchase);
// Track revenue with detailed product information
Singular.revenue("USD", 19.98,
"SKU123456",
"Premium Sword",
"Weapons",
2,
9.99
);
// Track revenue from a pre-built JSON payload
try {
JSONObject revenueJson = new JSONObject();
revenueJson.put("currency", "USD");
revenueJson.put("amount", 9.99);
revenueJson.put("product_id", "premium_gems");
Singular.revenue(revenueJson);
} catch (JSONException e) {
e.printStackTrace();
}
setCustomUserId
Método Singular.setCustomUserId
Establece un ID de usuario personalizado para el usuario actual. Esto le permite asociar los datos de Singular con su propio sistema de identificación de usuarios.
Firma
public static void setCustomUserId(String customUserId);
Ejemplo de uso
// Set custom user ID after user logs in
Singular.setCustomUserId("user_123456")
// Set custom user ID after user logs in
Singular.setCustomUserId("user_123456");
setDeviceCustomUserId
Función obsoleta: Use setCustomUserId en su lugar.
Método Singular.setDeviceCustomUserId
Establece un ID de usuario personalizado a nivel de dispositivo. Esto le permite asociar los datos de Singular con su propio sistema de identificación de usuarios a nivel de dispositivo.
Firma
public static void setDeviceCustomUserId(String customUserId);
Ejemplo de uso
// Set device-level custom user ID
Singular.setDeviceCustomUserId("device_user_123456")
// Set device-level custom user ID
Singular.setDeviceCustomUserId("device_user_123456");
setFCMDeviceToken
Método Singular.setFCMDeviceToken
Define el token de dispositivo FCM (Firebase Cloud Messaging) para notificaciones push y tracking de desinstalaciones. Debe llamarse cuando reciba el token FCM.
Firma
public static void setFCMDeviceToken(String fcmDeviceToken);
Ejemplo de uso
// In your Firebase Messaging Service
override fun onNewToken(token: String) {
super.onNewToken(token)
Singular.setFCMDeviceToken(token)
}
// In your Firebase Messaging Service
@Override
public void onNewToken(String token) {
super.onNewToken(token);
Singular.setFCMDeviceToken(token);
}
setGCMDeviceToken
Función obsoleta: Use setFCMDeviceToken en su lugar.
Método Singular.setGCMDeviceToken
Define el token de dispositivo GCM (Google Cloud Messaging). Este método está obsoleto; use setFCMDeviceToken en su lugar para Firebase Cloud Messaging.
Firma
public static void setGCMDeviceToken(String gcmDeviceToken);
Ejemplo de uso
// Deprecated - use setFCMDeviceToken instead
Singular.setGCMDeviceToken(token)
// Deprecated - use setFCMDeviceToken instead
Singular.setGCMDeviceToken(token);
setGlobalProperty
Método Singular.setGlobalProperty
Define una propiedad global que se enviará con todos los eventos. Esto le permite añadir atributos consistentes a todos los eventos sin tener que especificarlos cada vez.
Devuelve
false si la clave es null o está vacía, si el SDK no se ha inicializado o si el SDK ya tiene el máximo de 5 propiedades globales. Inspeccione el valor de retorno antes de suponer que la propiedad se almacenó.
Firma
public static boolean setGlobalProperty(final String key, final String value,
final boolean overrideExisting);
Ejemplo de uso
// Set a global property
val success = Singular.setGlobalProperty("user_tier", "premium", true)
if (success) {
println("Global property set successfully")
}
// Set a global property
boolean success = Singular.setGlobalProperty("user_tier", "premium", true);
if (success) {
System.out.println("Global property set successfully");
}
setIMEI
Método Singular.setIMEI
Define el IMEI del dispositivo para tracking. Es útil en regiones donde el tracking por IMEI está permitido y se prefiere.
Firma
public static void setIMEI(String imei);
Ejemplo de uso
// Set device IMEI
Singular.setIMEI("123456789012345")
// Set device IMEI
Singular.setIMEI("123456789012345");
setLimitAdvertisingIdentifiers
Método Singular.setLimitAdvertisingIdentifiers
Habilita o deshabilita el uso de identificadores publicitarios en aplicaciones con audiencia mixta. Esta opción afecta la forma en que el SDK recopila y utiliza los identificadores del dispositivo para tracking.
Firma
public static void setLimitAdvertisingIdentifiers(boolean enabled);
Ejemplo de uso
// Enable limited identifiers mode
Singular.setLimitAdvertisingIdentifiers(true)
// Enable limited identifiers mode
Singular.setLimitAdvertisingIdentifiers(true);
setWrapperNameAndVersion
Método Singular.setWrapperNameAndVersion
Define el nombre y la versión del wrapper cuando se usa el SDK a través de un wrapper (por ejemplo, Unity, React Native). Esto ayuda a identificar qué framework de wrapper se está utilizando.
Firma
public static void setWrapperNameAndVersion(final String wrapper, final String version);
Ejemplo de uso
// Set wrapper information
Singular.setWrapperNameAndVersion("Unity", "1.2.3")
// Set wrapper information
Singular.setWrapperNameAndVersion("Unity", "1.2.3");
stopAllTracking
Método Singular.stopAllTracking
Detiene todas las actividades de tracking. Use este método para deshabilitar el tracking cuando los usuarios opten por no participar o para cumplir con la privacidad.
Firma
public static void stopAllTracking();
Ejemplo de uso
// Stop tracking when user opts out
Singular.stopAllTracking()
// Stop tracking when user opts out
Singular.stopAllTracking();
trackingOptIn
Método Singular.trackingOptIn
Indica que el usuario ha optado por participar en el tracking. Llame a este método cuando el usuario consienta explícitamente el tracking y la recopilación de datos.
Firma
public static void trackingOptIn();
Ejemplo de uso
// User has opted in to tracking
Singular.trackingOptIn()
// User has opted in to tracking
Singular.trackingOptIn();
trackingUnder13
Método Singular.trackingUnder13
Indica que el usuario es menor de 13 años. Llame a este método para cumplir con COPPA y otras regulaciones para usuarios menores de 13 años.
Firma
public static void trackingUnder13();
Ejemplo de uso
// Notify Singular the user is under 13 years old
Singular.trackingUnder13()
// Notify Singular the user is under 13 years old
Singular.trackingUnder13();
unsetCustomUserId
Método Singular.unsetCustomUserId
Elimina el ID de usuario personalizado configurado previamente. Llame a este método cuando el usuario cierre sesión o cuando ya no quiera asociar eventos con el ID de usuario actual.
Firma
public static void unsetCustomUserId();
Ejemplo de uso
// Clear custom user ID when user logs out
Singular.unsetCustomUserId()
// Clear custom user ID when user logs out
Singular.unsetCustomUserId();
unsetGlobalProperty
Método Singular.unsetGlobalProperty
Elimina una propiedad global configurada previamente. Llame a este método cuando ya no quiera que una propiedad global específica se envíe con los eventos.
Firma
public static void unsetGlobalProperty(String key);
Ejemplo de uso
// Remove a global property
Singular.unsetGlobalProperty("user_tier")
// Remove a global property
Singular.unsetGlobalProperty("user_tier");