SDK do Android - Referência de métodos de configuração

SDK do Android - Referência de configuração

Este documento fornece uma referência abrangente de todas as opções de configuração disponíveis no Singular SDK para aplicativos Android. O objeto SingularConfig permite personalizar o comportamento do SDK, incluindo configurações de rastreamento, opções de atribuição, controles de privacidade e muito mais. Cada método de configuração é apresentado com uma descrição, uma assinatura e exemplos práticos de uso.

Exemplo completo de configuração

Configuração abrangente do SDK

O exemplo a seguir demonstra como criar uma configuração abrangente encadeando vários métodos de configuração.

Exemplo completo

Kotlin Java
// User details are hashed by the SDK before they are sent
val userDetails = SingularUserDetails()
userDetails.setEmail("user@example.com")
userDetails.setPhoneNumber("+15551234567")

// Create comprehensive configuration
val config = SingularConfig("SDK KEY", "YOUR_SECRET")
    // Basic options
    .withSessionTimeoutInSec(120)
    .withLoggingEnabled()
    .withLogLevel(Log.VERBOSE)

    // User identification
    .withCustomUserId("user_123456")

    // Global properties
    .withGlobalProperty("app_version", "1.2.3", true)
    .withGlobalProperty("user_type", "premium", true)

    // Deep links
    .withOpenURI(intent.data)
    .withSingularLink(intent, { params ->
        params.deeplink?.let { deeplink ->
            println("Deep link: $deeplink")
            handleDeepLink(deeplink)
        }
    }, 10)

    // Attribution callback
    .withSingularDeviceAttribution { attributionData ->
        println("Attribution: $attributionData")
    }

    // Push notifications
    .withFCMDeviceToken(fcmToken)

    // Privacy settings
    .withLimitDataSharing(false)

    // Email attribution
    .withESPDomains(listOf("mailchimp.com", "sendgrid.net"))

    // Facebook integration
    .withFacebookAppId("YOUR_FACEBOOK_APP_ID")

    // User details
    .withUserDetails(userDetails)

// Initialize the SDK
Singular.init(context, config)

Constructor

Construtor SingularConfig

Inicializa um novo objeto SingularConfig com sua chave de API e seu segredo. Este é o primeiro passo para configurar o Singular SDK.

Assinatura

public SingularConfig(String apiKey, String secret);

Exemplo de uso

Kotlin Java
// Create configuration object
val config = SingularConfig("SDK KEY", "YOUR_SECRET")

withBrandedDomains

Método SingularConfig.withBrandedDomains

Define domínios de marca para a atribuição da web para o aplicativo. Isso permite especificar domínios personalizados que devem ser rastreados para fins de atribuição.

Chamar este método substitui quaisquer domínios de marca definidos anteriormente. Passe a lista completa em uma única chamada em vez de encadear várias chamadas.

Assinatura

public SingularConfig withBrandedDomains(List<String> brandedDomains);

Exemplo de uso

Kotlin Java
// Set branded domains for web-to-app attribution
val brandedDomains = listOf("yourcompany.com", "go.yourcompany.com")
val config = SingularConfig("API_KEY", "SECRET")
    .withBrandedDomains(brandedDomains)

withCustomSdid

Método SingularConfig.withCustomSdid

Define um SDID (Singular Device ID) personalizado. Isso permite que você forneça seu próprio identificador de dispositivo em vez de usar o gerado pela Singular.

Assinatura

public SingularConfig withCustomSdid(String customSdid, SDIDAccessorHandler accessorHandler);

Exemplo de uso

Kotlin Java
// Set custom SDID with callback
val config = SingularConfig("API_KEY", "SECRET")
    .withCustomSdid("custom-device-id-12345", object : SDIDAccessorHandler {
        override fun didSetSdid(result: String) {
            println("SDID was set: $result")
            // Perform any actions needed after SDID is set
        }

        override fun sdidReceived(result: String) {
            println("SDID received: $result")
            // Existing SDID returned by the SDK
        }
    })

withCustomUserId

Método SingularConfig.withCustomUserId

Define um ID de usuário personalizado durante a inicialização do SDK. Isso permite que você associe os dados do Singular ao seu próprio sistema de identificação de usuários desde o início.

Assinatura

public SingularConfig withCustomUserId(String customUserId);

Exemplo de uso

Kotlin Java
// Set custom user ID at initialization
val config = SingularConfig("API_KEY", "SECRET")
    .withCustomUserId("user_123456")

withESPDomains

Método SingularConfig.withESPDomains

Define os domínios de ESP (provedor de serviços de email) para atribuição por email. Isso permite especificar quais domínios de email devem ser considerados para atribuição.

Chamar este método substitui quaisquer domínios de ESP definidos anteriormente. Passe a lista completa em uma única chamada em vez de encadear várias chamadas.

Assinatura

public SingularConfig withESPDomains(List<String> espDomains);

Exemplo de uso

Kotlin Java
// Set ESP domains for email attribution
val espDomains = listOf("mailchimp.com", "sendgrid.net", "campaign-monitor.com")
val config = SingularConfig("API_KEY", "SECRET")
    .withESPDomains(espDomains)

withFacebookAppId

Método SingularConfig.withFacebookAppId

Define o ID do aplicativo do Facebook para a integração de atribuição do Facebook. Isso permite que o SDK rastreie a atribuição de campanhas do Facebook.

Assinatura

public SingularConfig withFacebookAppId(String facebookAppId);

Exemplo de uso

Kotlin Java
// Set Facebook App ID
val config = SingularConfig("API_KEY", "SECRET")
    .withFacebookAppId("YOUR_FACEBOOK_APP_ID")

withFCMDeviceToken

Método SingularConfig.withFCMDeviceToken

Define o token de dispositivo do FCM (Firebase Cloud Messaging) na inicialização. Isso habilita o rastreamento de notificações push e a detecção de desinstalações desde o início.

A chamada é ignorada se o token for null ou vazio. Invoque este método apenas quando você tiver um token FCM válido.

Assinatura

public SingularConfig withFCMDeviceToken(String fcmDeviceToken);

Exemplo de uso

Kotlin Java
// Set FCM token at initialization if available
val config = SingularConfig("API_KEY", "SECRET")
    .withFCMDeviceToken(fcmToken)

withGlobalProperty

Método SingularConfig.withGlobalProperty

Define uma propriedade global durante a inicialização do SDK. Essa propriedade será enviada com todos os eventos rastreados pelo SDK. É um método de configuração que permite encadeamento.

O SDK suporta no máximo 5 propriedades globais. Chamadas adicionais além desse limite são ignoradas silenciosamente.

Assinatura

public SingularConfig withGlobalProperty(String key, String value, boolean overrideExisting);

Exemplo de uso

Kotlin Java
// Add global properties at initialization
val config = SingularConfig("API_KEY", "SECRET")
    .withGlobalProperty("app_version", "1.2.3", true)
    .withGlobalProperty("user_type", "free", true)

withIMEI

Método SingularConfig.withIMEI

Define o IMEI do dispositivo para rastreamento na inicialização. Útil em regiões onde o rastreamento por IMEI é permitido e preferido.

Assinatura

public SingularConfig withIMEI(String imei);

Exemplo de uso

Kotlin Java
// Set device IMEI at initialization
val config = SingularConfig("API_KEY", "SECRET")
    .withIMEI("123456789012345")

withLimitAdvertisingIdentifiers

Método SingularConfig.withLimitAdvertisingIdentifiers

Habilita o modo de identificadores de publicidade limitados em aplicativos com público misto. Essa opção afeta a forma como o SDK coleta e utiliza identificadores do dispositivo para rastreamento.

Assinatura

public SingularConfig withLimitAdvertisingIdentifiers();

Exemplo de uso

Kotlin Java
// Enable limited identifiers mode
val config = SingularConfig("API_KEY", "SECRET")
    .withLimitAdvertisingIdentifiers()

withLimitDataSharing

Método SingularConfig.withLimitDataSharing

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

Assinatura

public SingularConfig withLimitDataSharing(boolean shouldLimitDataSharing);

Exemplo de uso

Kotlin Java
// Enable limited data sharing at initialization
val config = SingularConfig("API_KEY", "SECRET")
    .withLimitDataSharing(true)

withLogLevel

Método SingularConfig.withLogLevel

Define o nível de log para os registros do SDK. Os níveis disponíveis são:

  • NONE = -1

  • VERBOSE = Log.VERBOSE (constante do Android, valor numérico 2)

  • DEBUG = Log.DEBUG (3)

  • INFO = Log.INFO (4)

  • WARNING = Log.WARN (5)

  • ERROR = Log.ERROR (6)

O nível de log padrão é Log.ERROR. Para que qualquer saída seja emitida, o logging também deve ser habilitado via withLoggingEnabled().

Assinatura

public SingularConfig withLogLevel(int level);

Exemplo de uso

Kotlin Java
import android.util.Log

// Set verbose logging for detailed debugging
val config = SingularConfig("API_KEY", "SECRET")
    .withLoggingEnabled()
    .withLogLevel(Log.VERBOSE)

withLoggingEnabled

Método SingularConfig.withLoggingEnabled

Habilita o logging do SDK. Útil para depuração e solução de problemas durante o desenvolvimento. Recomenda-se desativar o logging em builds de produção.

Assinatura

public SingularConfig withLoggingEnabled();

Exemplo de uso

Kotlin Java
// Enable logging for debug builds
val config = SingularConfig("API_KEY", "SECRET")
    .withLoggingEnabled()

withOAIDCollection

Método SingularConfig.withOAIDCollection

Habilita a coleta de OAID (Open Anonymous Device Identifier). É usado principalmente para rastreamento na China, onde os Google Play Services não estão disponíveis.

Assinatura

public SingularConfig withOAIDCollection();

Exemplo de uso

Kotlin Java
// Enable OAID collection for China
val config = SingularConfig("API_KEY", "SECRET")
    .withOAIDCollection()

withOpenURI

Método SingularConfig.withOpenURI

Define o URI que abriu o aplicativo. É usado para atribuição de deep links e deve ser definido quando o aplicativo é aberto por meio de um deep link.

Assinatura

public SingularConfig withOpenURI(Uri openUri);

Exemplo de uso

Kotlin Java
// In your Activity's onCreate or onNewIntent
val uri = intent.data
val config = SingularConfig("API_KEY", "SECRET")
    .withOpenURI(uri)

withPushNotificationPayload

Método SingularConfig.withPushNotificationPayload

Define o payload de notificação push para atribuição. Isso permite que o SDK processe os dados da notificação push durante a inicialização.

Assinatura

public SingularConfig withPushNotificationPayload(Intent intent, String[] ... pushNotificationLinkPath);

Exemplo de uso

Kotlin Java
// Set push notification payload with custom link paths
val config = SingularConfig("API_KEY", "SECRET")
    .withPushNotificationPayload(
        intent,
        arrayOf("data", "deeplink"),
        arrayOf("notification", "data", "url"),
        arrayOf("custom", "link")
    )

withSdidAccessorHandler

Método SingularConfig.withSdidAccessorHandler

Define uma função de callback a ser chamada quando o SDID (Singular Device ID) é recebido. Isso permite que você acesse o SDID assim que ele estiver disponível.

Assinatura

public SingularConfig withSdidAccessorHandler(SDIDAccessorHandler accessorHandler);

Exemplo de uso

Kotlin Java
// Set callback for when SDID is received
val config = SingularConfig("API_KEY", "SECRET")
    .withSdidAccessorHandler(object : SDIDAccessorHandler {
        override fun didSetSdid(result: String) {
            println("SDID was set: $result")
        }

        override fun sdidReceived(result: String) {
            println("SDID received: $result")
            // Store or use the SDID as needed
            storeDeviceIdentifier(result)
        }
    })

withSessionTimeoutInSec

Método SingularConfig.withSessionTimeoutInSec

Define o tempo limite da sessão em segundos. Determina por quanto tempo a sessão do usuário dura após o aplicativo ir para segundo plano. O valor padrão é 60 segundos.

Assinatura

public SingularConfig withSessionTimeoutInSec(long timeout);

Exemplo de uso

Kotlin Java
// Set session timeout to 2 minutes
val config = SingularConfig("API_KEY", "SECRET")
    .withSessionTimeoutInSec(120)

withSingularDeviceAttribution

Método SingularConfig.withSingularDeviceAttribution

Recurso BETA: Define uma função de callback a ser invocada quando os dados de atribuição do dispositivo estiverem disponíveis na resposta de /start . O callback é executado em uma thread de segundo plano, portanto despache qualquer trabalho de UI para a thread principal.

Apenas os campos que têm valor são incluídos, então verifique se a chave existe antes de lê-la. A maioria das instalações retorna um subconjunto: os campos presentes dependem do touchpoint que o Singular correspondeu.

Chave Tipo Notas
network String Sempre presente quando o callback é executado. "Organic" quando nenhum touchpoint foi correspondido.
campaign_id String Presente quando o touchpoint o fornece.
campaign_name String Presente quando o touchpoint o fornece.
subcampaign_id String Presente quando o touchpoint o fornece. Não está disponível em todas as fontes.
subcampaign_name String Presente quando o touchpoint o fornece. Não está disponível em todas as fontes.
creative_id String Presente quando o touchpoint o fornece. Não está disponível em todas as fontes.
creative_name String Presente quando o touchpoint o fornece. Não está disponível em todas as fontes.
passthrough String Presente quando valores de passthrough estavam anexados ao link.
match_type String Presente quando o touchpoint o fornece. Fale com o Singular se precisar do conjunto de valores.
click_timestamp Long Presente quando o touchpoint o fornece. Microssegundos epoch — divida por 1.000.000 para obter segundos.

O callback só é invocado quando a resposta de /start contém um objeto attribution_info . Para instalações orgânicas, apenas o campo network é preenchido.

Assinatura

public SingularConfig withSingularDeviceAttribution(SingularDeviceAttributionHandler handler);

Exemplo de uso

Kotlin Java
// Set device attribution callback
val config = SingularConfig("API_KEY", "SECRET")
      .withSingularDeviceAttribution { attributionData ->
          println("Attribution data received: $attributionData")

          val source         = attributionData["network"]        as? String
          val campaignName   = attributionData["campaign_name"]  as? String
          val campaignId     = attributionData["campaign_id"]    as? String
          val clickTimestamp = attributionData["click_timestamp"]?.toString()?.toLongOrNull()

          campaignName?.let { showCampaignSpecificContent(it) }
      }

withSingularLink

Métodos SingularConfig.withSingularLink

Configura Singular Links (deep links) para atribuição. Este método configura o handler para processar deep links e o tempo limite para a resolução de links curtos.

Quando o argumento shortlinkTimeoutSec é omitido, o SDK utiliza um padrão de 10 segundos. Quando a ação do intent é ACTION_VIEW, o SDK também marca a sessão como aberta com um deep link.

Assinaturas

public SingularConfig withSingularLink(Intent intent, SingularLinkHandler handler);

public SingularConfig withSingularLink(Intent intent, SingularLinkHandler handler,
                                       long shortlinkTimeoutSec);

Exemplo de uso

Kotlin Java
// Set Singular Links handler
val config = SingularConfig("API_KEY", "SECRET")
    .withSingularLink(intent, { params ->
        // Check if we have a deep link
        params.deeplink?.let { deeplink ->
            println("Deep link received: $deeplink")
            // Navigate based on the deep link
            navigateToScreen(deeplink)
        }

        // Check if this is a deferred deep link
        if (params.isDeferred) {
            println("This is a deferred deep link")
        }

        // Access passthrough parameters
        params.passthrough?.let { passthrough ->
            println("Passthrough data: $passthrough")
        }
    }, 10)

withUserDetails

Método SingularConfig.withUserDetails

Anexa os User Details (endereço de e-mail e número de telefone) na inicialização para que sejam enviados desde a primeira sessão. Passe um objeto SingularUserDetails antes de chamar Singular.init. O SDK normaliza os valores e aplica hash SHA-256 antes de eles saírem do dispositivo, portanto endereços de e-mail e números de telefone brutos nunca são transmitidos.

Disponível na versão 12.16.0 e superiores do SDK do Android. Para o conjunto completo de setters, as regras de validação e os métodos setUserDetails / clearUserDetails em tempo de execução, consulte Configurando um ID de usuário e User Details hasheados.

Observação: Os valores definidos aqui são armazenados criptografados no dispositivo e persistem entre inicializações do app até que você chame clearUserDetails. Chamar este método novamente em uma inicialização posterior não apaga os valores armazenados anteriormente.

Importante: Este método não está disponível na versão Kids do SDK. Além disso, enquanto o Limit Data Sharing estiver habilitado, o payload de User Details é excluído de todas as solicitações.

Assinatura

public SingularConfig withUserDetails(SingularUserDetails userDetails);

Exemplo de uso

Kotlin Java
// Attach user details at initialization
val userDetails = SingularUserDetails()
userDetails.setEmail("user@example.com")
userDetails.setPhoneNumber("+15551234567")

val config = SingularConfig("API_KEY", "SECRET")
    .withUserDetails(userDetails)