SDK de Android - Referencia de métodos

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

Kotlin Java
// 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)

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

Kotlin Java
// 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

Kotlin Java
// 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")
        }
    }
)

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

Kotlin Java
// 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)

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

Kotlin Java
// 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

Kotlin Java
// 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)

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

Kotlin Java
// Get all global properties
val properties = Singular.getGlobalProperties()
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

Kotlin Java
// Check if data sharing is limited
val isLimited = Singular.getLimitDataSharing()
if (isLimited) {
    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

Kotlin Java
// Get the current session ID
val sessionId = Singular.getSessionId()
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

Kotlin Java
// 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)

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

Kotlin Java
// Check if tracking is stopped
if (Singular.isAllTrackingStopped()) {
    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

Kotlin Java
// 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

Kotlin Java
override fun 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

Kotlin Java
override fun 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

Kotlin Java
// 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

Kotlin Java
// 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)

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

Kotlin Java
// 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

Kotlin Java
// 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

Kotlin Java
// In your Firebase Messaging Service
override fun onNewToken(token: String) {
    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

Kotlin Java
// 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

Kotlin Java
// Set a global property
val success = Singular.setGlobalProperty("user_tier", "premium", true)
if (success) {
    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

Kotlin Java
// 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

Kotlin Java
// 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

Kotlin Java
// 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

Kotlin Java
// 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

Kotlin Java
// 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

Kotlin Java
// 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

Kotlin Java
// 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

Kotlin Java
// Remove a global property
Singular.unsetGlobalProperty("user_tier")