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

Seguir
Avatar
Jared Ornstead
Updated
Documento

SDK do Android - Referência de Métodos de Configuração

O Singular SDK fornece um sistema de configuração flexível através da classe SingularConfig. Este documento descreve todas as opções de configuração disponíveis e como usá-las ao inicializar o SDK.

withCustomSdid

Método SingularConfig.withCustomSdid

Caraterística da empresa: Define um Singular Device ID (SDID) personalizado e um manipulador para acessá-lo.

Assinatura

public SingularConfig withCustomSdid(String customSdid, SDIDAccessorHandler accessorHandler)

Exemplo de utilização

Java
SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withCustomSdid("custom-device-id-12345", new SDIDAccessorHandler() {
        @Override
        public void onSDIDAccessed(String sdid) {
            // Handle SDID access
            Log.d("Singular", "SDID accessed: " + sdid);
        }
    });

withCustomUserId

Método SingularConfig.withCustomUserId

Define uma ID de utilizador personalizada durante a inicialização.

Assinatura

public SingularConfig withCustomUserId(String customUserId)

Exemplo de utilização

Java
SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withCustomUserId("user_12345");

withDDLHandler

Método SingularConfig.withDDLHandler

Define um manipulador para deep links diferidos.

Assinatura

public SingularConfig withDDLHandler(DeferredDeepLinkHandler handler)

Exemplo de utilização

Java
SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withDDLHandler(new DeferredDeepLinkHandler() {
        @Override
        public void onResolved(String resolvedLink) {
            if (resolvedLink != null) {
                // Handle the deferred deep link
                Log.d("Singular", "Deferred deep link: " + resolvedLink);
            }
        }
    });

withDDLTimeoutInSec

Método SingularConfig.withDDLTimeoutInSec

Define o tempo limite para a resolução diferida de deep links em segundos.

Assinatura

public SingularConfig withDDLTimeoutInSec(long timeout)

Exemplo de utilização

Java
SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withDDLHandler(deferredDeepLinkHandler)
    .withDDLTimeoutInSec(10); // 10 seconds timeout

withESPDomains

Método SingularConfig.withESPDomains

Define uma lista de domínios ESP (Email Service Provider) para o tratamento da atribuição de campanhas de correio eletrónico.

Assinatura

public SingularConfig withESPDomains(List espDomains)

Exemplo de utilização

Java
List<String> espDomains = new ArrayList<>();
espDomains.add("email.example.com");
espDomains.add("newsletter.example.com");

SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withESPDomains(espDomains);

withFacebookAppId

Método SingularConfig.withFacebookAppId

Define a ID do aplicativo do Facebook para atribuição do Facebook.

Assinatura

public SingularConfig withFacebookAppId(String facebookAppId)

Exemplo de uso

Java
SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withFacebookAppId("123456789012345");

withFCMDeviceToken

Método SingularConfig.withFCMDeviceToken

Define o token do dispositivo do Firebase Cloud Messaging durante a inicialização.

Assinatura

public SingularConfig withFCMDeviceToken(String fcmDeviceToken)

Exemplo de uso

Java
SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withFCMDeviceToken("eKh2BNP-Txy4XrjDGmw...");

withGlobalProperty

Método SingularConfig.withGlobalProperty

Define uma propriedade global durante a inicialização que será incluída em todos os eventos.

Assinatura

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

Exemplo de uso

Java
SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withGlobalProperty("app_version", "2.1.0", true)
    .withGlobalProperty("user_type", "free", true);

withIMEI

Método SingularConfig.withIMEI

Define o IMEI do dispositivo para rastreamento durante a inicialização.

Assinatura

public SingularConfig withIMEI(String imei)

Exemplo de utilização

Java
// Note: Requires READ_PHONE_STATE permission
String imei = null;
if (ContextCompat.checkSelfPermission(this, Manifest.permission.READ_PHONE_STATE) 
        == PackageManager.PERMISSION_GRANTED) {
    TelephonyManager telephonyManager = (TelephonyManager) getSystemService(Context.TELEPHONY_SERVICE);
    imei = telephonyManager.getDeviceId();
}

SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withIMEI(imei);

withLimitAdvertisingIdentifiers

Método SingularConfig.withLimitAdvertisingIdentifiers

Limita a utilização de identificadores de publicidade durante a inicialização.

Assinatura

public SingularConfig withLimitAdvertisingIdentifiers()

Exemplo de utilização

Java
SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withLimitAdvertisingIdentifiers();

withLimitDataSharing

Método SingularConfig.withLimitDataSharing

Controla se a partilha de dados com parceiros e redes deve ser limitada durante a inicialização.

Assinatura

public SingularConfig withLimitDataSharing(boolean shouldLimitDataSharing)

Exemplo de utilização

Java
SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withLimitDataSharing(true);

withLogLevel

Método SingularConfig.withLogLevel

Define o nível de registo para os registos do SDK.

Assinatura

public SingularConfig withLogLevel(int level)

Exemplo de utilização

Java
import android.util.Log;

SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withLoggingEnabled()
    .withLogLevel(Log.VERBOSE); // Use Log.VERBOSE, Log.DEBUG, Log.INFO, Log.WARN, Log.ERROR

withLoggingEnabled

Método SingularConfig.withLoggingEnabled

Ativa o registo para o SDK.

Assinatura

public SingularConfig withLoggingEnabled()

Exemplo de utilização

Java
SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withLoggingEnabled();

withOAIDCollection

Método SingularConfig.withOAIDCollection

Permite a recolha de OAID (Open Anonymous Device Identifier) para dispositivos chineses.

Assinatura

public SingularConfig withOAIDCollection()

Exemplo de utilização

Java
SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withOAIDCollection();

withOpenURI

Método SingularConfig.withOpenURI

Define o URI que abriu o aplicativo para atribuição.

Assinatura

public SingularConfig withOpenURI(Uri openUri)

Exemplo de uso

Java
// In your Activity's onCreate method
Uri data = getIntent().getData();
SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withOpenURI(data);

withPushNotificationPayload

Método SingularConfig.withPushNotificationPayload

Define o payload da notificação push e o caminho para extrair o deep link do payload.

Assinatura

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

Exemplo de utilização

Java
// In your Activity that handles push notifications
Intent intent = getIntent();
SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withPushNotificationPayload(intent, new String[]{"singular_link"}, new String[]{"data", "deeplink"});

withSdidAccessorHandler

Método SingularConfig.withSdidAccessorHandler

Caraterística da empresa: Define um manipulador para aceder ao ID de Dispositivo Singular (SDID).

Assinatura

public SingularConfig withSdidAccessorHandler(SDIDAccessorHandler accessorHandler)

Exemplo de utilização

Java
SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withSdidAccessorHandler(new SDIDAccessorHandler() {
        @Override
        public void onSDIDAccessed(String sdid) {
            // Handle SDID access
            Log.d("Singular", "SDID accessed: " + sdid);
        }
    });

withSessionTimeoutInSec

Método SingularConfig.withSessionTimeoutInSec

Define o tempo limite da sessão em segundos.

Assinatura

public SingularConfig withSessionTimeoutInSec(long timeout)

Exemplo de utilização

Java
SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withSessionTimeoutInSec(60); // 60 seconds timeout

withSingularDeviceAttribution

Método SingularConfig.withSingularDeviceAttribution

Funcionalidade BETA: Define uma função de tratamento para receber dados de atribuição de dispositivos quando estes estiverem disponíveis.

Assinatura

public SingularConfig withSingularDeviceAttribution(SingularDeviceAttributionHandler handler)

Exemplo de uso

Java
SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withSingularDeviceAttribution(new SingularDeviceAttributionHandler() {
        @Override
        public void onDeviceAttributionInfoReceived(Map deviceAttributionData) {
            // Handle device attribution data
            if (deviceAttributionData != null) {
                for (Object key : deviceAttributionData.keySet()) {
                    Log.d("Singular", key + ": " + deviceAttributionData.get(key));
                }
            }
        }
    });

withSingularLink

Método SingularConfig.withSingularLink

Define o tratamento de links singulares com um retorno de chamada para links resolvidos.

Assinatura

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

Exemplo de utilização

Java
// In your Activity's onCreate method
Intent intent = getIntent();
SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withSingularLink(intent, new SingularLinkHandler() {
        @Override
        public void onResolved(SingularLinkParams params) {
            if (params != null) {
                // Handle the deep link
                String deeplink = params.getDeeplink();
                if (deeplink != null) {
                    Log.d("Singular", "Deep link: " + deeplink);
                    // Navigate to the appropriate screen
                }
                
                // Get passthrough parameters
                String passthrough = params.getPassthrough();
                if (passthrough != null) {
                    Log.d("Singular", "Passthrough: " + passthrough);
                }
                
                // Check if this is a deferred deep link
                boolean isDeferred = params.isDeferred();
                Log.d("Singular", "Is deferred: " + isDeferred);
            }
        }
    }, 10); // 10 seconds timeout

Exemplo de configuração completa

Encadeando várias opções de configuração

Aqui está um exemplo completo mostrando como encadear múltiplas opções de configuração ao inicializar o Singular SDK.

Exemplo de uso

Java
import android.app.Activity;
import android.content.Intent;
import android.net.Uri;
import android.os.Bundle;
import android.util.Log;

import com.singular.sdk.Singular;
import com.singular.sdk.SingularConfig;
import com.singular.sdk.SingularLinkHandler;
import com.singular.sdk.SingularLinkParams;
import com.singular.sdk.SingularDeviceAttributionHandler;

import java.util.ArrayList;
import java.util.List;
import java.util.Map;

public class MainActivity extends Activity {
    
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        
        // Get the intent that started this activity
        Intent intent = getIntent();
        
        // Initialize Singular SDK with advanced configuration
        SingularConfig config = new SingularConfig("SDK KEY", "YOUR_SECRET")
            // Enable logging for debugging
            .withLoggingEnabled()
            .withLogLevel(Log.DEBUG)
            
            // Set custom user ID if available
            .withCustomUserId("user_12345")
            
            // Configure session timeout
            .withSessionTimeoutInSec(60)
            
            // Set global properties for all events
            .withGlobalProperty("app_version", "2.1.0", true)
            .withGlobalProperty("user_type", "premium", true)
            
            // Handle deep links
            .withSingularLink(intent, new SingularLinkHandler() {
                @Override
                public void onResolved(SingularLinkParams params) {
                    if (params != null) {
                        String deeplink = params.getDeeplink();
                        if (deeplink != null) {
                            Log.d("Singular", "Deep link: " + deeplink);
                            // Navigate based on deep link
                        }
                    }
                }
            }, 10)
            
            // Handle deferred deep links
            .withDDLHandler(new DeferredDeepLinkHandler() {
                @Override
                public void onResolved(String resolvedLink) {
                    if (resolvedLink != null) {
                        Log.d("Singular", "Deferred deep link: " + resolvedLink);
                        // Handle deferred deep link
                    }
                }
            })
            .withDDLTimeoutInSec(5)
            
            // Get device attribution data
            .withSingularDeviceAttribution(new SingularDeviceAttributionHandler() {
                @Override
                public void onDeviceAttributionInfoReceived(Map deviceAttributionData) {
                    if (deviceAttributionData != null) {
                        for (Object key : deviceAttributionData.keySet()) {
                            Log.d("Singular", key + ": " + deviceAttributionData.get(key));
                        }
                    }
                }
            })
            
            // Facebook attribution
            .withFacebookAppId("123456789012345")
            
            // Configure data sharing limitations for privacy
            .withLimitDataSharing(true)
            .withLimitAdvertisingIdentifiers();
        
        // Initialize the SDK with the configuration
        Singular.init(this, config);
    }
    
    @Override
    protected void onResume() {
        super.onResume();
        Singular.onActivityResumed();
    }
    
    @Override
    protected void onPause() {
        super.onPause();
        Singular.onActivityPaused();
    }
}