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
// 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)
// Create ad data object
SingularAdData adData = new SingularAdData("AdMob", "USD", 0.05)
.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
// Clear all global properties
Singular.clearGlobalProperties()
// 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
// 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")
}
}
)
// Create a short link for referral
try {
JSONObject passthroughParams = new JSONObject();
passthroughParams.put("channel", "sms");
passthroughParams.put("campaign", "summer_promo");
Singular.createReferrerShortLink(
"https://sample.sng.link/B4tbm/v8fp",
"John Doe",
"aq239897",
passthroughParams,
new ShortLinkHandler() {
@Override
public void onSuccess(String link) {
System.out.println("Generated short link: " + link);
// Share the link with users
}
@Override
public void onError(String error) {
System.out.println("Error creating short link: " + error);
}
}
);
} catch (JSONException e) {
e.printStackTrace();
}
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
// 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)
// Track a custom revenue event
Singular.customRevenue("premium_subscription", "USD", 9.99);
// Track a custom revenue event with attributes
Map<String, Object> attributes = new HashMap<>();
attributes.put("product_id", "com.app.gems_pack_small");
attributes.put("quantity", 1);
Singular.customRevenue("in_app_purchase", "USD", 5.99, attributes);
// Track a custom revenue event from a pre-built JSON payload
try {
JSONObject customRevenueJson = new JSONObject();
customRevenueJson.put("currency", "USD");
customRevenueJson.put("amount", 5.99);
customRevenueJson.put("product_id", "com.app.gems_pack_small");
Singular.customRevenue("in_app_purchase", customRevenueJson);
} catch (JSONException e) {
e.printStackTrace();
}
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
// 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"
)
// 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
// 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)
// Track an event with JSON object
try {
JSONObject eventData = new JSONObject();
eventData.put("level_id", 5);
eventData.put("score", 12500);
eventData.put("time_spent", 120);
eventData.put("difficulty", "medium");
Singular.eventJSON("level_completed", eventData);
} catch (JSONException e) {
e.printStackTrace();
}
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
// Get all global properties
val properties = Singular.getGlobalProperties()
println("Global properties: $properties")
// Get all global properties
Map<String, String> properties = Singular.getGlobalProperties();
System.out.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
// Check if data sharing is limited
val isLimited = Singular.getLimitDataSharing()
if (isLimited) {
println("Data sharing is currently limited")
}
// Check if data sharing is limited
boolean isLimited = Singular.getLimitDataSharing();
if (isLimited) {
System.out.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
// Get the current session ID
val sessionId = Singular.getSessionId()
println("Current session ID: $sessionId")
// Get the current session ID
long sessionId = Singular.getSessionId();
System.out.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
// 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)
// Simple initialization with API key and secret
Singular.init(context, "SDK KEY", "YOUR_SECRET");
// Initialize with configuration object
SingularConfig config = new 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
// Check if tracking is stopped
if (Singular.isAllTrackingStopped()) {
println("Tracking is currently stopped")
}
// Check if tracking is stopped
if (Singular.isAllTrackingStopped()) {
System.out.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
// 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)
// 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
override fun onPause() {
super.onPause()
Singular.onActivityPaused()
}
@Override
protected void 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
override fun onResume() {
super.onResume()
Singular.onActivityResumed()
}
@Override
protected void 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
// Resume tracking when user opts back in
Singular.resumeAllTracking()
// 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
// 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)
// Track revenue with currency and amount
Singular.revenue("USD", 9.99);
// Track revenue with additional attributes
Map<String, Object> attributes = new HashMap<>();
attributes.put("product_id", "premium_gems");
attributes.put("quantity", 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
try {
JSONObject revenueJson = new JSONObject();
revenueJson.put("currency", "USD");
revenueJson.put("amount", 9.99);
revenueJson.put("product_id", "premium_gems");
Singular.revenue(revenueJson);
} catch (JSONException e) {
e.printStackTrace();
}
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
// Set custom user ID after user logs in
Singular.setCustomUserId("user_123456")
// 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
// Set device-level custom user ID
Singular.setDeviceCustomUserId("device_user_123456")
// 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
// In your Firebase Messaging Service
override fun onNewToken(token: String) {
super.onNewToken(token)
Singular.setFCMDeviceToken(token)
}
// In your Firebase Messaging Service
@Override
public void onNewToken(String token) {
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
// Deprecated - use setFCMDeviceToken instead
Singular.setGCMDeviceToken(token)
// 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
// Set a global property
val success = Singular.setGlobalProperty("user_tier", "premium", true)
if (success) {
println("Global property set successfully")
}
// Set a global property
boolean success = Singular.setGlobalProperty("user_tier", "premium", true);
if (success) {
System.out.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
// Set device IMEI
Singular.setIMEI("123456789012345")
// 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
// Enable limited identifiers mode
Singular.setLimitAdvertisingIdentifiers(true)
// 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
// Set wrapper information
Singular.setWrapperNameAndVersion("Unity", "1.2.3")
// 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
// Stop tracking when user opts out
Singular.stopAllTracking()
// 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
// User has opted in to tracking
Singular.trackingOptIn()
// 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
// Notify Singular the user is under 13 years old
Singular.trackingUnder13()
// 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
// Clear custom user ID when user logs out
Singular.unsetCustomUserId()
// 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
// Remove a global property
Singular.unsetGlobalProperty("user_tier")
// Remove a global property
Singular.unsetGlobalProperty("user_tier");