Documento

SDK do Unity - Referência de métodos

Este documento fornece uma referência abrangente para todos os métodos disponíveis no SDK Singular para aplicativos Unity. O Singular SDK do Unity envolve os SDKs nativos do iOS e do Android, fornecendo uma interface C# unificada para atribuição móvel, deep linking, rastreamento de receita e análise. Cada método é apresentado com uma descrição, assinatura e exemplos práticos de utilização.

Receita de anúncios

Método SingularSDK.AdRevenue

Monitoriza as receitas de anúncios das plataformas de mediação. Este método permite-lhe reportar as receitas geradas pelas impressões de anúncios na sua aplicação Unity, apoiando a atribuição e a análise do ROI para a monetização de anúncios.

Assinatura

public static void AdRevenue(string currency, double amount)

Exemplo de utilização

// Track ad revenue from an ad impression
SingularSDK.AdRevenue("USD", 0.05);

ClearGlobalProperties

Método SingularSDK.ClearGlobalProperties

Remove todas as propriedades globais que foram definidas anteriormente. As propriedades globais são pares de valores chave que são automaticamente incluídos em todos os eventos monitorizados pelo SDK.

Assinatura

public static void ClearGlobalProperties()

Exemplo de utilização

// Clear all global properties
SingularSDK.ClearGlobalProperties();

createReferrerShortLink

Método SingularSDK.createReferrerShortLink

Este método gera um link curto que pode ser partilhado pelos utilizadores para rastrear referências e atribuir novas instalações a referenciadores específicos.

Assinatura

public static void createReferrerShortLink(string baseLink, string referrerName, 
    string referrerId, Dictionary<string, string> passthroughParams, 
    ShortLinkCallback completionHandler)

Exemplo de uso

// Create a referrer short link
var passthroughParams = new Dictionary<string, string>
{
    { "promo_code", "WELCOME10" },
    { "campaign", "spring_2024" }
};

SingularSDK.createReferrerShortLink(
    "https://yourapp.sng.link/12345",
    "John Doe",
    "user_12345",
    passthroughParams,
    (data, error) =>
    {
        if (error == null)
        {
            Debug.Log("Short link created: " + data);
        }
        else
        {
            Debug.LogError("Error creating short link: " + error);
        }
    }
);

CustomRevenue

Método SingularSDK.CustomRevenue

Rastreia um evento de receita personalizado com um nome de evento especificado. Isto permite-lhe acompanhar as receitas de outras fontes que não as compras in-app, tais como subscrições ou outros métodos de monetização.

Assinatura

public static void CustomRevenue(string eventName, string currency, double amount)

public static void CustomRevenue(Dictionary<string, object> args, 
    string eventName, string currency, double amount)

Exemplo de utilização

// Track custom revenue event
SingularSDK.CustomRevenue("subscription_renewal", "USD", 9.99);

// Track custom revenue with additional attributes
var attributes = new Dictionary<string, object>
{
    { "subscription_type", "premium" },
    { "billing_period", "monthly" }
};

SingularSDK.CustomRevenue(attributes, "subscription_renewal", "USD", 9.99);

EndSingularSession

Método SingularSDK.EndSingularSession

Finaliza manualmente a sessão Singular atual. Normalmente, é chamado quando a aplicação vai para segundo plano, caso seja necessário um controlo explícito sobre a gestão da sessão.

Assinatura

public static void EndSingularSession()

Exemplo de uso

// End the current session
SingularSDK.EndSingularSession();

Evento

Método SingularSDK.Event

Rastreia um evento personalizado em seu aplicativo Unity. Os eventos podem ser rastreados apenas com um nome ou com atributos adicionais como pares de valores chave para análises mais detalhadas.

Assinatura

public static void Event(string name)

public static void Event(Dictionary<string, object> args, string name)

public static void Event(string name, params object[] args)

Exemplo de uso

// Track a simple event
SingularSDK.Event("level_completed");

// Track event with dictionary attributes
var attributes = new Dictionary<string, object>
{
    { "level", 5 },
    { "score", 1250 },
    { "time_seconds", 45.3 }
};
SingularSDK.Event(attributes, "level_completed");

// Track event with params array (key-value pairs)
SingularSDK.Event("item_purchased", 
    "item_name", "Golden Sword",
    "item_category", "weapons",
    "price", 4.99);

ObterAPID

Método SingularSDK.GetAPID

Retorna o APID (Attribution Platform ID) da Singular para o dispositivo atual. Esse identificador é usado internamente pela Singular para atribuição e análise. Somente iOS.

Assinatura

public static string GetAPID()

Exemplo de uso

// Get the APID
string apid = SingularSDK.GetAPID();
Debug.Log("APID: " + apid);

GetGlobalProperties

Método SingularSDK.GetGlobalProperties

Recupera todas as propriedades globais definidas atualmente como uma cadeia de caracteres JSON. As propriedades globais são pares de valores chave que são automaticamente incluídos em cada evento monitorizado.

Assinatura

public static string GetGlobalProperties()

Exemplo de uso

// Get all global properties
string globalProps = SingularSDK.GetGlobalProperties();
Debug.Log("Global Properties: " + globalProps);

ObterIDFA

Método SingularSDK.GetIDFA

Devolve o IDFA (Identificador para Anunciantes) para o dispositivo iOS atual. Este método requer uma autorização ATT (App Tracking Transparency) adequada. Apenas iOS.

Assinatura

public static string GetIDFA()

Exemplo de utilização

// Get the IDFA (iOS only)
string idfa = SingularSDK.GetIDFA();
Debug.Log("IDFA: " + idfa);

GetLimitDataSharing

Método SingularSDK.GetLimitDataSharing

Devolve o estado atual da limitação da partilha de dados. Isto indica se o SDK está atualmente a limitar a recolha e partilha de dados com base nas definições de privacidade.

Assinatura

public static bool GetLimitDataSharing()

Exemplo de utilização

// Check if data sharing is limited
bool isLimited = SingularSDK.GetLimitDataSharing();
Debug.Log("Data sharing limited: " + isLimited);

HandlePushNotification

Método SingularSDK.HandlePushNotification

Processa cargas de notificação push para atribuição e tratamento de links profundos. Esse método deve ser chamado quando seu aplicativo recebe uma notificação push. Somente iOS.

Assinatura

public static void HandlePushNotification(Dictionary<string, string> pushNotificationPayload)

Exemplo de uso

// Handle push notification (iOS only)
var pushPayload = new Dictionary<string, string>
{
    { "aps", "{"alert":"New message"}" },
    { "deep_link", "myapp://promo/spring2024" }
};

SingularSDK.HandlePushNotification(pushPayload);

InAppPurchase

Método SingularSDK.InAppPurchase

Rastreia compras in-app do Unity IAP. Este método é compatível com o Unity IAP 4.x e 5.x e valida automaticamente os recibos de compra com a Apple e o Google.

Assinatura

public static void InAppPurchase(Product product, Dictionary<string, object> attributes)

Exemplo de utilização

// Track in-app purchase
void OnPurchaseComplete(Product product)
{
    var attributes = new Dictionary<string, object>
    {
        { "category", "consumables" },
        { "location", "main_store" }
    };

    SingularSDK.InAppPurchase(product, attributes);
}

InicializarSingularSDK

Método SingularSDK.InitializeSingularSDK

Inicializa manualmente o Singular SDK. Este método só deve ser chamado se você tiver definido InitializeOnAwake como false na configuração do SDK. Caso contrário, o SDK é inicializado automaticamente.

Assinatura

public static void InitializeSingularSDK()

Exemplo de uso

// Manually initialize the SDK (only if InitializeOnAwake = false)
SingularSDK.InitializeSingularSDK();

IsAllTrackingStopped

Método SingularSDK.IsAllTrackingStopped

Retorna se todo o rastreamento foi interrompido. Quando a monitorização é interrompida, o SDK não envia quaisquer eventos nem recolhe quaisquer dados.

Assinatura

public static bool IsAllTrackingStopped()

Exemplo de utilização

// Check if tracking is stopped
bool isTrackingStopped = SingularSDK.IsAllTrackingStopped();
Debug.Log("Tracking stopped: " + isTrackingStopped);

Limitar a partilha de dados

Método SingularSDK.LimitDataSharing

Define se o SDK deve limitar a partilha de dados. Quando ativado, o SDK restringirá determinadas actividades de recolha e partilha de dados para cumprir os regulamentos de privacidade.

Assinatura

public static void LimitDataSharing(bool limitDataSharingValue)

Exemplo de utilização

// Enable limited data sharing based on user consent
SingularSDK.LimitDataSharing(true);

RegisterDeviceTokenForUninstall

Método SingularSDK.RegisterDeviceTokenForUninstall

Registra o token do dispositivo para rastreamento de desinstalação. Isso permite que o Singular detecte quando os usuários desinstalam seu aplicativo. Somente iOS.

Assinatura

public static void RegisterDeviceTokenForUninstall(string APNSToken)

Exemplo de uso

// Register APNS token for uninstall tracking (iOS only)
void OnTokenReceived(string token)
{
    SingularSDK.RegisterDeviceTokenForUninstall(token);
}

RestartSingularSession

Método SingularSDK.RestartSingularSession

Reinicia manualmente a sessão do Singular. Normalmente, é chamado quando a aplicação regressa ao primeiro plano, caso seja necessário um controlo explícito da gestão da sessão.

Assinatura

public static void RestartSingularSession(string key, string secret)

Exemplo de uso

// Restart the session
SingularSDK.RestartSingularSession("SDK KEY", "YOUR_SECRET");

RetomarTudoRastreamento

Método SingularSDK.ResumeAllTracking

Retoma todo o rastreamento depois que ele foi interrompido anteriormente. Isto reactiva o seguimento de eventos e a recolha de dados.

Assinatura

public static void ResumeAllTracking()

Exemplo de utilização

// Resume tracking
SingularSDK.ResumeAllTracking();

Receita

Método SingularSDK.Revenue

Rastreia um evento de receita. Este é o principal método para rastrear compras e outros eventos de monetização que não são rastreados automaticamente através do IAP do Unity.

Assinatura

public static void Revenue(string currency, double amount)

public static void Revenue(Dictionary<string, object> args, 
    string currency, double amount)

Exemplo de utilização

// Track simple revenue
SingularSDK.Revenue("USD", 9.99);

// Track revenue with attributes
var attributes = new Dictionary<string, object>
{
    { "product_id", "premium_upgrade" },
    { "product_name", "Premium Subscription" },
    { "product_category", "subscriptions" }
};

SingularSDK.Revenue(attributes, "USD", 9.99);

SetAge

Método SingularSDK.SetAge

Define a idade do utilizador para rastreio demográfico. A idade tem de estar compreendida entre 0 e 100. Apenas iOS.

Assinatura

public static void SetAge(int age)

Exemplo de utilização

// Set user age (iOS only)
SingularSDK.SetAge(28);

SetConversionValueUpdatedHandler

Método SingularSDK.SetConversionValueUpdatedHandler

Define um manipulador de retorno de chamada para actualizações do valor de conversão da SKAdNetwork (iOS 14+). Este manipulador é chamado sempre que o valor de conversão é atualizado. Apenas iOS.

Assinatura

public static void SetConversionValueUpdatedHandler(SingularConversionValueUpdatedHandler handler)

Exemplo de utilização

// Set conversion value updated handler (iOS only)
SingularSDK.SetConversionValueUpdatedHandler((conversionValue) =>
{
    Debug.Log("Conversion value updated: " + conversionValue);
});

SetConversionValuesUpdatedHandler

Método SingularSDK.SetConversionValuesUpdatedHandler

Define um manipulador de chamada de retorno para actualizações dos valores de conversão da SKAdNetwork 4.0+. Este manipulador fornece o valor de conversão, o valor de conversão grosseiro e o estado do bloqueio.

Assinatura

public static void SetConversionValuesUpdatedHandler(SingularConversionValuesUpdatedHandler handler)

Exemplo de utilização

// Set conversion values updated handler (iOS only)
SingularSDK.SetConversionValuesUpdatedHandler((conversionValue, coarse, lockWindow) =>
{
    Debug.Log($"CV: {conversionValue}, Coarse: {coarse}, Lock: {lockWindow}");
});

SetCustomUserId

Método SingularSDK.SetCustomUserId

Define uma ID de usuário personalizada para associar a todos os eventos rastreados. Isto permite-lhe associar os dados Singular ao seu próprio sistema de identificação de utilizadores.

Assinatura

public static void SetCustomUserId(string customUserId)

Exemplo de uso

// Set custom user ID
SingularSDK.SetCustomUserId("user_123456");

SetDeviceCustomUserId

Método SingularSDK.SetDeviceCustomUserId

Define um ID de usuário personalizado no nível do dispositivo. Este é diferente do ID de utilizador personalizado normal e persiste nas sessões da aplicação ao nível do dispositivo.

Assinatura

public static void SetDeviceCustomUserId(string customUserId)

Exemplo de utilização

// Set device-level custom user ID
SingularSDK.SetDeviceCustomUserId("device_user_789");

SetFCMDeviceToken

Método SingularSDK.SetFCMDeviceToken

Define o token de dispositivo FCM (Firebase Cloud Messaging) para rastreamento de notificações push e deteção de desinstalação. Apenas para Android.

Assinatura

public static void SetFCMDeviceToken(string fcmDeviceToken)

Exemplo de uso

// Set FCM token (Android only)
void OnFCMTokenReceived(string token)
{
    SingularSDK.SetFCMDeviceToken(token);
}

SetGender

Método SingularSDK.SetGender

Define o género do utilizador para controlo demográfico. Aceita "m" para homem ou "f" para mulher. Apenas iOS.

Assinatura

public static void SetGender(string gender)

Exemplo de utilização

// Set user gender (iOS only)
SingularSDK.SetGender("f");

SetGlobalProperty

Método SingularSDK.SetGlobalProperty

Define uma propriedade global que será enviada com todos os eventos. As propriedades globais são pares de valores chave que persistem em vários eventos até serem apagadas ou alteradas.

Assinatura

public static bool SetGlobalProperty(string key, string value, bool overrideExisting)

Exemplo de uso

// Set a global property
bool success = SingularSDK.SetGlobalProperty("user_level", "premium", true);

// Set multiple global properties
SingularSDK.SetGlobalProperty("app_version", "2.1.0", true);
SingularSDK.SetGlobalProperty("platform", "unity", true);

DefinirIMEI

Método SingularSDK.SetIMEI

Define o IMEI do dispositivo para rastreio. Isto é útil em regiões onde o rastreio do IMEI é permitido e preferido. Apenas no Android.

Assinatura

public static void SetIMEI(string imei)

Exemplo de utilização

// Set device IMEI (Android only)
SingularSDK.SetIMEI("123456789012345");

SetLimitAdvertisingIdentifiers (Definir limite de identificadores de publicidade)

Método SingularSDK.SetLimitAdvertisingIdentifiers

Ativa o modo de identificadores de publicidade limitados. Isto afecta a forma como o SDK recolhe e utiliza identificadores de dispositivos para rastreio, adequado para aplicações de audiências mistas.

Assinatura

public static void SetLimitAdvertisingIdentifiers(bool isEnabled)

Exemplo de utilização

// Enable limited advertising identifiers mode
SingularSDK.SetLimitAdvertisingIdentifiers(true);

SetSingularDeviceAttributionCallbackHandler

Método SingularSDK.SetSingularDeviceAttributionCallbackHandler

Define um manipulador de retorno de chamada para receber dados de atribuição do dispositivo. Este manipulador é invocado quando os dados de atribuição ficam disponíveis, permitindo-lhe aceder às informações da campanha e da fonte.

Crie um script C# AttributionCallback com o código do manipulador abaixo
Crie um Objeto Emtpy na Hierarquia e coloque-o abaixo do SingularSDKObject
Adicione um Componente de Script ao Objeto Vazio associando o Script Handler AttributionCallback

Assinatura

public static void SetSingularDeviceAttributionCallbackHandler(
    SingularDeviceAttributionCallbackHandler handler)

Exemplo de uso

using System.Collections;
using System.Collections.Generic;
using UnityEngine;
using Singular;

public class AttributionCallback : MonoBehaviour, SingularDeviceAttributionCallbackHandler 
{
    void Awake()
    {
        Debug.Log("Registering SingularDeviceAttributionCallbackHandler");
        SingularSDK.SetSingularDeviceAttributionCallbackHandler(this);
    }

    public void OnSingularDeviceAttributionCallback(Dictionary attributionInfo) {
		foreach(var kvp in attributionInfo)
		{
			Debug.Log($"OnSingularDeviceAttributionCallback Key: {kvp.Key}, Value: {kvp.Value}");
		}
	}
}

SetSingularLinkHandler

Método SingularSDK.SetSingularLinkHandler

Define um manipulador de retorno de chamada para Singular Links (links profundos). Esse manipulador é chamado quando um link profundo é resolvido, fornecendo parâmetros de link e dados de passagem.

Crie um script C# DeepLinkManager com o código do manipulador abaixo
Crie um Objeto Emtpy na Hierarquia e coloque-o abaixo do SingularSDKObject
Adicione um Componente de Script ao Objeto Vazio associando o Script Handler DeepLinkManager

Assinatura

public static void SetSingularLinkHandler(SingularLinkHandler linkHandler)

Exemplo de uso

using System.Collections;
using System.Collections.Generic;
using UnityEngine;
using Singular;

public class DeepLinkManager : MonoBehaviour, SingularLinkHandler
{
    void Awake()
    {
        Debug.Log("Registering SingularLink Handler");
        SingularSDK.SetSingularLinkHandler(this);
    }

    public void OnSingularLinkResolved(SingularLinkParams linkParams)
    {
        Debug.Log("SingularLink Resolved");

        // Extract parameters from the tracking link
        string deeplink = linkParams.Deeplink;
        string passthrough = linkParams.Passthrough;
        bool isDeferred = linkParams.IsDeferred;

        // Log the parameters
        Debug.Log($"SingularLink Deeplink: {deeplink ?? "null"}");
        Debug.Log($"SingularLink Passthrough: {passthrough ?? "null"}");
        Debug.Log($"SingularLink is Deferred: {isDeferred}");

        // Handle deep link routing
        if (!string.IsNullOrEmpty(deeplink))
        {
            HandleDeepLink(deeplink, isDeferred);
        }
    }

    private void HandleDeepLink(string url, bool isDeferred)
    {
        // Your deep link routing logic here
        Debug.Log($"SingularLink Routing to: {url} (Deferred: {isDeferred})");

        // Example: Parse the URL and navigate to the appropriate screen
        // if (url.Contains("product"))
        // {
        //     NavigateToProduct(url);
        // }
    }
}

SetSingularSdidAccessorHandler

Método SingularSDK.SetSingularSdidAccessorHandler

Define um manipulador de retorno de chamada para receber a ID de Dispositivo Singular (SDID). Esse manipulador é chamado quando o SDID fica disponível após a inicialização do SDK.

Crie um script C# SDIDManager com o código Handler abaixo
Crie um Objeto Emtpy na Hierarquia e coloque-o abaixo do SingularSDKObject
Adicione um Componente de Script ao Objeto Vazio associando o Script Handler SDIDManager

Assinatura

public static void SetSingularSdidAccessorHandler(SingularSdidAccessorHandler handler)

Exemplo de uso

using System.Collections;
using System.Collections.Generic;
using UnityEngine;
using Singular;

public class SDIDManager : MonoBehaviour, SingularSdidAccessorHandler
{
    void Awake()
    {
        Debug.Log("Registering SingularSdidAccessorHandler");
        SingularSDK.SetSingularSdidAccessorHandler(this);
    }

    public void DidSetSdid(string sdid)
    {
        Debug.Log($"SDID Set: {sdid}");
    }

    public void SdidReceived(string sdid)
    {
        Debug.Log($"SDID Set: {sdid}");
        // Store or use the SDID as needed
    }   
}

SkanRegisterAppForAdNetworkAttribution

Método SingularSDK.SkanRegisterAppForAdNetworkAttribution

Regista a aplicação para atribuição de SKAdNetwork. Este método deve ser chamado no início do ciclo de vida da aplicação para suporte de SKAdNetwork no iOS 14.5+. Apenas iOS.

Assinatura

public static void SkanRegisterAppForAdNetworkAttribution()

Exemplo de utilização

// Register for SKAdNetwork attribution (iOS only)
SingularSDK.SkanRegisterAppForAdNetworkAttribution();

SkanUpdateConversionValue

Método SingularSDK.SkanUpdateConversionValue

Actualiza manualmente o valor de conversão SKAdNetwork. Este método é utilizado quando a gestão manual do valor de conversão está activada. Apenas iOS.

Assinatura

public static bool SkanUpdateConversionValue(int conversionValue)

public static bool SkanUpdateConversionValue(int conversionValue, int coarse, bool lockWindow)

Exemplo de utilização

// Update conversion value (iOS only)
bool success = SingularSDK.SkanUpdateConversionValue(5);

// Update with coarse value and lock (SKAdNetwork 4.0+)
bool success2 = SingularSDK.SkanUpdateConversionValue(10, 2, false);

StopAllTracking

Método SingularSDK.StopAllTracking

Interrompe todo o seguimento e recolha de dados. Quando a monitorização é interrompida, o SDK não envia quaisquer eventos nem recolhe quaisquer dados até que a monitorização seja retomada.

Assinatura

public static void StopAllTracking()

Exemplo de utilização

// Stop all tracking
SingularSDK.StopAllTracking();

TrackingOptIn

Método SingularSDK.TrackingOptIn

Indica que o utilizador optou pelo rastreio. Este método deve ser chamado quando o utilizador consente explicitamente a recolha de dados e o rastreio.

Assinatura

public static void TrackingOptIn()

Exemplo de utilização

// User opted in to tracking
SingularSDK.TrackingOptIn();

TrackingUnder13

Método SingularSDK.TrackingUnder13

Indica que o utilizador tem menos de 13 anos, o que afecta a recolha de dados para cumprir os regulamentos COPPA (Children's Online Privacy Protection Act).

Assinatura

public static void TrackingUnder13()

Exemplo de utilização

// User is under 13 years old
SingularSDK.TrackingUnder13();

UnsetCustomUserId

Método SingularSDK.UnsetCustomUserId

Remove o ID de utilizador personalizado previamente definido. Depois de chamar este método, os eventos deixarão de estar associados a um ID de utilizador personalizado até que seja definido um novo.

Assinatura

public static void UnsetCustomUserId()

Exemplo de utilização

// Remove custom user ID (e.g., on logout)
SingularSDK.UnsetCustomUserId();

UnsetGlobalProperty

Método SingularSDK.UnsetGlobalProperty

Remove uma propriedade global específica por chave. Isto impede que a propriedade seja enviada com eventos subsequentes.

Assinatura

public static void UnsetGlobalProperty(string key)

Exemplo de uso

// Remove a specific global property
SingularSDK.UnsetGlobalProperty("user_level");