SDK do Android - Referência de métodos

SDK do Android - Referência de métodos

Esta referência abrangente documenta todos os métodos disponíveis no Singular SDK para aplicativos Android. O SDK oferece funcionalidade para inicialização, rastreamento de eventos, relatório de receita, atribuição, conformidade com privacidade de dados e configuração. Cada método é apresentado com uma descrição, uma assinatura e exemplos práticos de uso para ajudar os desenvolvedores a integrar os recursos do Singular SDK em seus aplicativos.

adRevenue

Método Singular.adRevenue

Rastreia eventos de receita de anúncios com informações detalhadas dos dados do anúncio. Este método permite reportar a receita gerada pelos anúncios exibidos em seu aplicativo.

Assinatura

public static void adRevenue(SingularAdData adData);

Exemplo 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

Remove todas as propriedades globais definidas anteriormente. É útil quando você precisa redefinir as propriedades globais, por exemplo, quando um usuário faz logout do seu aplicativo.

Assinatura

public static void clearGlobalProperties();

Exemplo de uso

Kotlin Java
// Clear all global properties
Singular.clearGlobalProperties()

createReferrerShortLink

Método Singular.createReferrerShortLink

Cria um link curto com informações de referenciador que pode ser usado para compartilhamento e atribuição. Este método gera links rastreáveis que podem ser compartilhados com usuários, permitindo atribuir instalações e atividades a fontes de referência específicas.

Assinatura

public static void createReferrerShortLink(String baseLink, String referrerName, String referrerId,
                                            JSONObject passthroughParams, ShortLinkHandler shortLinkHandler);

Exemplo 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

Rastreia eventos de receita personalizada com um nome de evento, moeda, valor e informações opcionais de produto. Isso permite um rastreamento de receita mais específico com nomes de evento personalizados.

Ao passar um objeto purchase, o SDK só extrai os detalhes de recibo, assinatura e SKU se ele for uma instância de com.android.billingclient.api.Purchase. Outros tipos recorrem a um evento de receita básico apenas com moeda e valor.

Assinaturas

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);

Exemplo 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

Rastreia eventos com o nome especificado e atributos personalizados opcionais. Use estes métodos para rastrear ações do usuário e engajamento dentro do seu aplicativo.

A sobrecarga com varargs espera pares chave/valor, portanto args deve conter um número par de elementos. Uma contagem ímpar faz com que a chamada retorne false sem enviar o evento.

Assinaturas

public static boolean event(String name);

public static boolean event(String name, String extra);

public static boolean event(String name, Object... args);

Exemplo 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

Rastreia eventos com um objeto JSON contendo atributos personalizados. Este método oferece maior flexibilidade para estruturas de dados de eventos complexas.

Assinatura

public static boolean eventJSON(String name, final JSONObject json);

Exemplo 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 as propriedades globais atualmente definidas. Este método retorna um mapa contendo todas as propriedades globais que foram definidas para o SDK.

Assinatura

public static Map<String, String> getGlobalProperties();

Exemplo de uso

Kotlin Java
// Get all global properties
val properties = Singular.getGlobalProperties()
println("Global properties: $properties")

getLimitDataSharing

Método Singular.getLimitDataSharing

Recupera o status atual da limitação de compartilhamento de dados. Este método retorna um booleano indicando se o compartilhamento de dados está atualmente limitado.

Retorna false se o SDK não tiver sido inicializado, independentemente de qualquer valor definido anteriormente via SingularConfig.withLimitDataSharing. Sempre interprete false no contexto, e não como prova de que o usuário optou por participar.

Assinatura

public static boolean getLimitDataSharing();

Exemplo 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

Retorna o ID da sessão atual. Pode ser usado para rastrear e correlacionar eventos dentro da mesma sessão.

Retorna Constants.INVALID se o SDK não tiver sido inicializado. Sempre chame Singular.init() antes de depender desse valor.

Assinatura

public static long getSessionId();

Exemplo de uso

Kotlin Java
// Get the current session ID
val sessionId = Singular.getSessionId()
println("Current session ID: $sessionId")

init

Método Singular.init

Inicializa o Singular SDK com a chave de API e o segredo fornecidos, ou com um objeto de configuração. Este é o primeiro método que você deve chamar para começar a usar o Singular SDK.

Assinaturas

public static boolean init(final Context context, final String apiKey, final String secret);

public static boolean init(final Context context, final SingularConfig config);

Exemplo 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 se todo o rastreamento está atualmente interrompido. Este método retorna um booleano indicando se o rastreamento está atualmente interrompido.

Retorna false se o SDK não tiver sido inicializado. Trate false como "não interrompido ou não inicializado", e não como "rastreando ativamente".

Assinatura

public static boolean isAllTrackingStopped();

Exemplo de uso

Kotlin Java
// Check if tracking is stopped
if (Singular.isAllTrackingStopped()) {
    println("Tracking is currently stopped")
}

limitDataSharing

Método Singular.limitDataSharing

Define o status de limitação de compartilhamento de dados. Use este método para limitar o compartilhamento de dados com base no consentimento do usuário ou em requisitos de privacidade.

Assinatura

public static void limitDataSharing(boolean shouldLimitDataSharing);

Exemplo 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 o SDK quando uma activity é pausada. Isso deve ser chamado a partir do método onPause() das suas activities para rastrear o ciclo de vida da sessão.

Assinatura

public static void onActivityPaused();

Exemplo de uso

Kotlin Java
override fun onPause() {
    super.onPause()
    Singular.onActivityPaused()
}

onActivityResumed

Método Singular.onActivityResumed

Notifica o SDK quando uma activity é retomada. Isso deve ser chamado a partir do método onResume() das suas activities para rastrear o ciclo de vida da sessão.

Assinatura

public static void onActivityResumed();

Exemplo de uso

Kotlin Java
override fun onResume() {
    super.onResume()
    Singular.onActivityResumed()
}

resumeAllTracking

Método Singular.resumeAllTracking

Retoma todas as atividades de rastreamento que foram interrompidas anteriormente. Use este método para reativar o rastreamento depois de ele ter sido interrompido.

Assinatura

public static void resumeAllTracking();

Exemplo de uso

Kotlin Java
// Resume tracking when user opts back in
Singular.resumeAllTracking()

revenue

Métodos Singular.revenue

Rastreia eventos de receita com vários parâmetros, incluindo moeda, valor e detalhes do produto. Isso permite um rastreamento abrangente de receita para o seu aplicativo.

Ao passar um objeto purchase, o SDK só extrai os detalhes de recibo, assinatura e SKU se ele for uma instância de com.android.billingclient.api.Purchase. Outros tipos recorrem a um evento de receita básico apenas com moeda e valor.

Assinaturas

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);

Exemplo 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

Define um ID de usuário personalizado para o usuário atual. Isso permite que você associe os dados do Singular ao seu próprio sistema de identificação de usuários.

Assinatura

public static void setCustomUserId(String customUserId);

Exemplo de uso

Kotlin Java
// Set custom user ID after user logs in
Singular.setCustomUserId("user_123456")

setDeviceCustomUserId

Recurso obsoleto: Use setCustomUserId em vez deste.

Método Singular.setDeviceCustomUserId

Define um ID de usuário personalizado no nível do dispositivo. Isso permite que você associe os dados do Singular ao seu próprio sistema de identificação de usuários no nível do dispositivo.

Assinatura

public static void setDeviceCustomUserId(String customUserId);

Exemplo de uso

Kotlin Java
// Set device-level custom user ID
Singular.setDeviceCustomUserId("device_user_123456")

setFCMDeviceToken

Método Singular.setFCMDeviceToken

Define o token de dispositivo do FCM (Firebase Cloud Messaging) para notificações push e rastreamento de desinstalações. Deve ser chamado quando você recebe o token FCM.

Assinatura

public static void setFCMDeviceToken(String fcmDeviceToken);

Exemplo de uso

Kotlin Java
// In your Firebase Messaging Service
override fun onNewToken(token: String) {
    super.onNewToken(token)
    Singular.setFCMDeviceToken(token)
}

setGCMDeviceToken

Recurso obsoleto: Use setFCMDeviceToken em vez deste.

Método Singular.setGCMDeviceToken

Define o token de dispositivo do GCM (Google Cloud Messaging). Este método está obsoleto; use setFCMDeviceToken em vez disso para o Firebase Cloud Messaging.

Assinatura

public static void setGCMDeviceToken(String gcmDeviceToken);

Exemplo de uso

Kotlin Java
// Deprecated - use setFCMDeviceToken instead
Singular.setGCMDeviceToken(token)

setGlobalProperty

Método Singular.setGlobalProperty

Define uma propriedade global que será enviada com todos os eventos. Isso permite adicionar atributos consistentes a todos os eventos sem precisar especificá-los a cada vez.

Retorna false se a chave for null ou vazia, se o SDK não tiver sido inicializado ou se o SDK já contiver o máximo de 5 propriedades globais. Inspecione o valor de retorno antes de presumir que a propriedade foi armazenada.

Assinatura

public static boolean setGlobalProperty(final String key, final String value,
                                        final boolean overrideExisting);

Exemplo 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 o IMEI do dispositivo para rastreamento. Útil em regiões onde o rastreamento por IMEI é permitido e preferido.

Assinatura

public static void setIMEI(String imei);

Exemplo de uso

Kotlin Java
// Set device IMEI
Singular.setIMEI("123456789012345")

setLimitAdvertisingIdentifiers

Método Singular.setLimitAdvertisingIdentifiers

Habilita ou desabilita o uso de identificadores de publicidade em aplicativos com público misto. Essa opção afeta como o SDK coleta e usa identificadores do dispositivo para rastreamento.

Assinatura

public static void setLimitAdvertisingIdentifiers(boolean enabled);

Exemplo de uso

Kotlin Java
// Enable limited identifiers mode
Singular.setLimitAdvertisingIdentifiers(true)

setWrapperNameAndVersion

Método Singular.setWrapperNameAndVersion

Define o nome e a versão do wrapper ao usar o SDK por meio de um wrapper (por exemplo, Unity, React Native). Isso ajuda a identificar qual framework wrapper está sendo usado.

Assinatura

public static void setWrapperNameAndVersion(final String wrapper, final String version);

Exemplo de uso

Kotlin Java
// Set wrapper information
Singular.setWrapperNameAndVersion("Unity", "1.2.3")

stopAllTracking

Método Singular.stopAllTracking

Interrompe todas as atividades de rastreamento. Use este método para desabilitar o rastreamento quando os usuários optarem por sair ou para conformidade com a privacidade.

Assinatura

public static void stopAllTracking();

Exemplo de uso

Kotlin Java
// Stop tracking when user opts out
Singular.stopAllTracking()

trackingOptIn

Método Singular.trackingOptIn

Indica que o usuário optou por participar do rastreamento. Chame este método quando o usuário consentir explicitamente com o rastreamento e a coleta de dados.

Assinatura

public static void trackingOptIn();

Exemplo de uso

Kotlin Java
// User has opted in to tracking
Singular.trackingOptIn()

trackingUnder13

Método Singular.trackingUnder13

Indica que o usuário tem menos de 13 anos de idade. Chame este método para estar em conformidade com a COPPA e outras regulamentações para usuários menores de 13 anos.

Assinatura

public static void trackingUnder13();

Exemplo de uso

Kotlin Java
// Notify Singular the user is under 13 years old
Singular.trackingUnder13()

unsetCustomUserId

Método Singular.unsetCustomUserId

Remove o ID de usuário personalizado definido anteriormente. Chame este método quando o usuário fizer logout ou quando você não quiser mais associar eventos ao ID de usuário atual.

Assinatura

public static void unsetCustomUserId();

Exemplo de uso

Kotlin Java
// Clear custom user ID when user logs out
Singular.unsetCustomUserId()

unsetGlobalProperty

Método Singular.unsetGlobalProperty

Remove uma propriedade global definida anteriormente. Chame este método quando você não quiser mais que uma propriedade global específica seja enviada com os eventos.

Assinatura

public static void unsetGlobalProperty(String key);

Exemplo de uso

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