SDK do Android - Referência de Configuração
Este documento fornece uma referência abrangente para 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, assinatura e exemplos práticos de uso.
Exemplo de configuração completa
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)
// Deferred deep links
.withDDLHandler { deeplink ->
deeplink?.let {
println("Deferred deep link: $it")
handleDeepLink(it)
}
}
.withDDLTimeoutInSec(60)
// 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)
// Deferred deep links
.withDDLHandler(new DeferredDeepLinkHandler() {
@Override
public void onDeferredDeepLink(String deeplink) {
if (deeplink != null) {
System.out.println("Deferred deep link: " + deeplink);
handleDeepLink(deeplink);
}
}
})
.withDDLTimeoutInSec(60)
// Attribution callback
.withSingularDeviceAttribution(new SingularDeviceAttributionHandler() {
@Override
public void onDeviceAttribution(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);Construtor
Construtor de SingularConfig
Inicializa um novo objeto SingularConfig com sua chave de API e segredo. Este é o primeiro passo na configuração do 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 atribuição web-to-app. Isto permite-lhe especificar domínios personalizados que devem ser controlados para efeitos de atribuição.
Assinatura
public SingularConfig withBrandedDomains(List<String> brandedDomains);Exemplo de utilização
// 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
Funcionalidade empresarial: Define um SDID (Singular Device ID) personalizado. Isto permite-lhe fornecer o seu próprio identificador de dispositivo em vez de utilizar o que é gerado pela Singular.
Assinatura
public SingularConfig withCustomSdid(String customSdid, SDIDAccessorHandler accessorHandler);Exemplo de utilização
// Set custom SDID with callback
val config = SingularConfig("API_KEY", "SECRET")
.withCustomSdid("custom-device-id-12345") { sdid ->
println("SDID was set: $sdid")
// Perform any actions needed after SDID is set
}// Set custom SDID with callback
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
.withCustomSdid("custom-device-id-12345", new SDIDAccessorHandler() {
@Override
public void onSdidReceived(String sdid) {
System.out.println("SDID was set: " + sdid);
// Perform any actions needed after SDID is set
}
});withCustomUserId
Método SingularConfig.withCustomUserId
Define um ID de usuário personalizado durante a inicialização do SDK. Isto permite-lhe associar os dados Singular ao seu próprio sistema de identificação de utilizadores 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");comDDLHandler
Método SingularConfig.withDDLHandler
Define um manipulador de callback para ligações diretas diferidas (DDL). Esta chamada de retorno será invocada quando uma ligação direta diferida for resolvida, permitindo-lhe tratar os dados da ligação direta na sua aplicação.
Assinatura
public SingularConfig withDDLHandler(DeferredDeepLinkHandler handler);Exemplo de uso
// Set deferred deep link handler
val config = SingularConfig("API_KEY", "SECRET")
.withDDLHandler { deeplink ->
if (deeplink != null) {
println("Deferred deep link received: $deeplink")
// Navigate to the appropriate screen
handleDeepLink(deeplink)
}
}// Set deferred deep link handler
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
.withDDLHandler(new DeferredDeepLinkHandler() {
@Override
public void onDeferredDeepLink(String deeplink) {
if (deeplink != null) {
System.out.println("Deferred deep link received: " + deeplink);
// Navigate to the appropriate screen
handleDeepLink(deeplink);
}
}
});withDDLTimeoutInSec
Método SingularConfig.withDDLTimeoutInSec
Define o tempo limite em segundos para a resolução diferida de links diretos. Isso determina quanto tempo o SDK aguardará por um deferred deep link antes de continuar com a inicialização. O valor padrão é 60 segundos.
Assinatura
public SingularConfig withDDLTimeoutInSec(long timeout);Exemplo de uso
// Set DDL timeout to 30 seconds
val config = SingularConfig("API_KEY", "SECRET")
.withDDLTimeoutInSec(30)// Set DDL timeout to 30 seconds
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
.withDDLTimeoutInSec(30);withESPDomains
Método SingularConfig.withESPDomains
Define os domínios ESP (Email Service Provider) para atribuição de correio eletrónico. Isto permite-lhe especificar quais os domínios de correio eletrónico que devem ser considerados para atribuição.
Assinatura
public SingularConfig withESPDomains(List<String> espDomains);Exemplo de utilização
// 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 a ID do aplicativo do Facebook para integração de atribuição do Facebook. Isso permite que o SDK rastreie a atribuição de campanha 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 do dispositivo FCM (Firebase Cloud Messaging) na inicialização. Isso permite o rastreamento de notificações push e a deteção de desinstalação desde o início.
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. Esta propriedade será enviada com todos os eventos monitorizados pelo SDK. Este é um método de configuração que permite a configuração encadeada.
Assinatura
public SingularConfig withGlobalProperty(String key, String value, boolean overrideExisting);Exemplo de utilização
// 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);comIMEI
Método SingularConfig.withIMEI
Define o IMEI do dispositivo para rastreamento na inicialização. Isto é útil em regiões onde a localização do IMEI é permitida e preferida.
Assinatura
public SingularConfig withIMEI(String imei);Exemplo de utilização
// 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
Esta opção afecta a forma como o SDK recolhe e utiliza identificadores de dispositivos para rastreio.
Assinatura
public SingularConfig withLimitAdvertisingIdentifiers();Exemplo de utilização
// 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 estado de limitação da partilha de dados na inicialização. Utilize este método para limitar a partilha de dados com base no consentimento do utilizador ou em requisitos de privacidade.
Assinatura
public SingularConfig withLimitDataSharing(boolean shouldLimitDataSharing);Exemplo de utilização
// 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 registo para o registo 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)
Assinatura
public SingularConfig withLogLevel(int level);Exemplo de utilização
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
Ativa o registo do SDK. Isto é útil para depuração e resolução de problemas durante o desenvolvimento. Recomenda-se a desativação do registo em compilações de produção.
Assinatura
public SingularConfig withLoggingEnabled();Exemplo de utilização
// 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
Ativa a coleção OAID (Open Anonymous Device Identifier). Este método é utilizado principalmente para o rastreio na China, onde o Google Play Services não está disponível.
Assinatura
public SingularConfig withOAIDCollection();Exemplo de utilização
// 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 a aplicação. Isso é usado para atribuição de links diretos e deve ser definido quando o aplicativo é aberto por meio de um link direto.
Assinatura
public SingularConfig withOpenURI(Uri openUri);Exemplo de utilização
// 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 a carga útil da 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
Caraterística da empresa: Define uma função de chamada de retorno a ser chamada quando o SDID (Singular Device ID) é recebido. Isto permite-lhe aceder ao SDID logo que este esteja disponível.
Assinatura
public SingularConfig withSdidAccessorHandler(SDIDAccessorHandler accessorHandler);Exemplo de utilização
// Set callback for when SDID is received
val config = SingularConfig("API_KEY", "SECRET")
.withSdidAccessorHandler { sdid ->
println("SDID received: $sdid")
// Store or use the SDID as needed
storeDeviceIdentifier(sdid)
}// Set callback for when SDID is received
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
.withSdidAccessorHandler(new SDIDAccessorHandler() {
@Override
public void onSdidReceived(String sdid) {
System.out.println("SDID received: " + sdid);
// Store or use the SDID as needed
storeDeviceIdentifier(sdid);
}
});withSessionTimeoutInSec
Método SingularConfig.withSessionTimeoutInSec
Define o tempo limite da sessão em segundos. Isto determina quanto tempo dura uma sessão de utilizador depois de a aplicação passar para segundo plano. O valor padrão é 60 segundos.
Assinatura
public SingularConfig withSessionTimeoutInSec(long timeout);Exemplo de utilização
// 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
Funcionalidade BETA: Define uma função de retorno de chamada a ser chamada quando os dados de atribuição do dispositivo estiverem disponíveis. Isto permite-lhe aceder aos dados de atribuição assim que estiverem disponíveis.
Assinatura
public SingularConfig withSingularDeviceAttribution(SingularDeviceAttributionHandler handler);Exemplo de utilização
// Set device attribution callback
val config = SingularConfig("API_KEY", "SECRET")
.withSingularDeviceAttribution { attributionData ->
println("Attribution data received: $attributionData")
// Access specific attribution parameters
val campaign = attributionData["campaign"] as? String
val source = attributionData["source"] as? String
val adSet = attributionData["adSet"] as? String
// Update UI or take actions based on attribution data
campaign?.let { showCampaignSpecificContent(it) }
}// Set device attribution callback
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
.withSingularDeviceAttribution(new SingularDeviceAttributionHandler() {
@Override
public void onDeviceAttribution(Map<String, Object> attributionData) {
System.out.println("Attribution data received: " + attributionData);
// Access specific attribution parameters
String campaign = (String) attributionData.get("campaign");
String source = (String) attributionData.get("source");
String adSet = (String) attributionData.get("adSet");
// Update UI or take actions based on attribution data
if (campaign != null) {
showCampaignSpecificContent(campaign);
}
}
});withSingularLink
Métodos de SingularConfig.withSingularLink
Configura os Singular Links (deep links) para atribuição. Este método define o manipulador para processar ligações profundas e o tempo limite para a resolução de ligações curtas.
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);