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

// 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")

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

// Create comprehensive configuration
SingularConfig config = new 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(getIntent().getData())
    .withSingularLink(getIntent(), new SingularLinkHandler() {
        @Override
        public void onResolved(SingularLinkParams params) {
            if (params.getDeeplink() != null) {
                System.out.println("Deep link: " + params.getDeeplink());
                handleDeepLink(params.getDeeplink());
            }
        }
    }, 10)

    // Attribution callback
    .withSingularDeviceAttribution(new SingularDeviceAttributionHandler() {
        @Override
        public void onDeviceAttributionInfoReceived(Map<String, Object> attributionData) {
            System.out.println("Attribution: " + attributionData);
        }
    })

    // Push notifications
    .withFCMDeviceToken(fcmToken)

    // Privacy settings
    .withLimitDataSharing(false)

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

    // Facebook integration
    .withFacebookAppId("YOUR_FACEBOOK_APP_ID");

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

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

// Create configuration object
SingularConfig config = new 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

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

// Set branded domains for web-to-app attribution
List<String> brandedDomains = Arrays.asList("yourcompany.com", "go.yourcompany.com");
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withBrandedDomains(brandedDomains);

withCustomSdid

Método SingularConfig.withCustomSdid

Recurso Enterprise: 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

// 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
        }
    })

// Set custom SDID with callback
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withCustomSdid("custom-device-id-12345", new SDIDAccessorHandler() {
        @Override
        public void didSetSdid(String result) {
            System.out.println("SDID was set: " + result);
            // Perform any actions needed after SDID is set
        }

        @Override
        public void sdidReceived(String result) {
            System.out.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

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

// Set custom user ID at initialization
SingularConfig config = new 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

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

// Set ESP domains for email attribution
List<String> espDomains = Arrays.asList("mailchimp.com", "sendgrid.net", "campaign-monitor.com");
SingularConfig config = new 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

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

// Set Facebook App ID
SingularConfig config = new 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

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

// Set FCM token at initialization if available
SingularConfig config = new 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

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

// Add global properties at initialization
SingularConfig config = new 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

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

// Set device IMEI at initialization
SingularConfig config = new 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

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

// Enable limited identifiers mode
SingularConfig config = new 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

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

// Enable limited data sharing at initialization
SingularConfig config = new 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

import android.util.Log

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

import android.util.Log;

// Set verbose logging for detailed debugging
SingularConfig config = new 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

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

// Enable logging for debug builds
SingularConfig config = new 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

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

// Enable OAID collection for China
SingularConfig config = new 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

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

// In your Activity's onCreate or onNewIntent
Uri uri = getIntent().getData();
SingularConfig config = new 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

// 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")
    )

// Set push notification payload with custom link paths
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withPushNotificationPayload(
        intent,
        new String[]{"data", "deeplink"},
        new String[]{"notification", "data", "url"},
        new String[]{"custom", "link"}
    );

withSdidAccessorHandler

Método SingularConfig.withSdidAccessorHandler

Recurso Enterprise: 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

// 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)
        }
    })

// Set callback for when SDID is received
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withSdidAccessorHandler(new SDIDAccessorHandler() {
        @Override
        public void didSetSdid(String result) {
            System.out.println("SDID was set: " + result);
        }

        @Override
        public void sdidReceived(String result) {
            System.out.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

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

// Set session timeout to 2 minutes
SingularConfig config = new 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.

Chave	Tipo	Observações
`network`	String	Fonte da atribuição. "organic" para instalações não atribuídas.
`campaign_id`	String	Presente apenas quando há atribuição.
`campaign_name`	String	Presente apenas quando há atribuição.
`click_timestamp`	Long (microssegundos epoch)	Presente apenas quando há atribuição. 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

// 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) }
      }

// Set device attribution callback
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
  .withSingularDeviceAttribution(new SingularDeviceAttributionHandler() {
    @Override
    public void onDeviceAttributionInfoReceived(Map<String, Object> attributionData) {
      Log.d("Singular", "Attribution data received: " + attributionData);
      String source        = (String) attributionData.get("network");
      String campaignName  = (String) attributionData.get("campaign_name");
      String campaignId    = (String) attributionData.get("campaign_id");
      Object clickTsObj    = attributionData.get("click_timestamp");
      Long   clickTimestamp = clickTsObj != null
          ? Long.parseLong(clickTsObj.toString())
          : null;
      if (campaignName != null) {
          showCampaignSpecificContent(campaignName);
      }
    }
});

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

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

// Set Singular Links handler
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withSingularLink(intent, new SingularLinkHandler() {
        @Override
        public void onResolved(SingularLinkParams params) {
            // Check if we have a deep link
            if (params.getDeeplink() != null) {
                System.out.println("Deep link received: " + params.getDeeplink());
                // Navigate based on the deep link
                navigateToScreen(params.getDeeplink());
            }

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

            // Access passthrough parameters
            if (params.getPassthrough() != null) {
                System.out.println("Passthrough data: " + params.getPassthrough());
            }
        }
    }, 10);

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

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

Exemplo completo de configuração

Configuração abrangente do SDK

Exemplo completo

Constructor

Construtor SingularConfig

Assinatura

Exemplo de uso

withBrandedDomains

Método SingularConfig.withBrandedDomains

Assinatura

Exemplo de uso

withCustomSdid

Método SingularConfig.withCustomSdid

Assinatura

Exemplo de uso

withCustomUserId

Método SingularConfig.withCustomUserId

Assinatura

Exemplo de uso

withESPDomains

Método SingularConfig.withESPDomains

Assinatura

Exemplo de uso

withFacebookAppId

Método SingularConfig.withFacebookAppId

Assinatura

Exemplo de uso

withFCMDeviceToken

Método SingularConfig.withFCMDeviceToken

Assinatura

Exemplo de uso

withGlobalProperty

Método SingularConfig.withGlobalProperty

Assinatura

Exemplo de uso

withIMEI

Método SingularConfig.withIMEI

Assinatura

Exemplo de uso

withLimitAdvertisingIdentifiers

Método SingularConfig.withLimitAdvertisingIdentifiers

Assinatura

Exemplo de uso

withLimitDataSharing

Método SingularConfig.withLimitDataSharing

Assinatura

Exemplo de uso

withLogLevel

Método SingularConfig.withLogLevel

Assinatura

Exemplo de uso

withLoggingEnabled

Método SingularConfig.withLoggingEnabled

Assinatura

Exemplo de uso

withOAIDCollection

Método SingularConfig.withOAIDCollection

Assinatura

Exemplo de uso

withOpenURI

Método SingularConfig.withOpenURI

Assinatura

Exemplo de uso

withPushNotificationPayload

Método SingularConfig.withPushNotificationPayload

Assinatura

Exemplo de uso

withSdidAccessorHandler

Método SingularConfig.withSdidAccessorHandler

Assinatura

Exemplo de uso

withSessionTimeoutInSec

Método SingularConfig.withSessionTimeoutInSec

Assinatura

Exemplo de uso

withSingularDeviceAttribution

Método SingularConfig.withSingularDeviceAttribution

Assinatura