Antes de começar: Pré-requisitos do SDK

• Siga as etapas em Integração de um SDK Singular:Planejamento e pré-requisitos.
  Essas etapas são pré-requisitos para qualquer integração do Singular SDK.
• Verifique se você usa o Google EDM4U, o Gerenciador de Dependências Externas do Google para Unity.
  O que é o Google EDM4U? Saiba mais [AQUI].
  

1. Instalar o SDK

1.1. Descarregamento e importação do pacote SDK

1.2. Configuração para Android

-keep class com.singular.sdk.** { *; }
-keep public class com.android.installreferrer.** { *; }
-keep public class com.singular.unitybridge.** { *; }

1.3. Dicas para iOS

pod repo update
pod update

// Impressão do identificador do fornecedor (IDFV) no console do Xcode para uso no console do Singular SDK
NSLog(@"Singular === IDFV: %@", [[[UIDevice currentDevice] identifierForVendor] UUIDString]);

2. Integração do SDK

2.1. Criar o SingularSDKObject

Adicionar o SingularSDKObject à hierarquia

Configurar as definições do SingularSDKObject

1. No painel Inspeção do SingularSDKObject, cole a Chave do SDK Singular e o Segredo do SDK nos respectivos campos. Para obter a chave e o segredo do SDK, inicie sessão na sua conta Singular e aceda a"Developer Tools > SDK Integration > SDK Keys").
   
   
   
   IMPORTANTE: NÃO USE a Chave da API de relatórios do Singular ou os dados do SDK não serão recebidos. Siga as instruções acima para obter a chave e o segredo corretos.
   
   
   

   Se a chave e o segredo do SDK do Singular forem aplicados incorretamente, os dados não serão enviados ao Singular.
   Teste sua implementação usando o Singular SDK Console para verificar o comportamento correto.

Outras opções do painel de inspeção:

2.2. Usando SKAdNetwork

A partir da versão 4.0.17 do Unity SDK, a SKAdNetwork é ativada por padrão. Ela é ativada no Modo gerenciado (no qual a Singular atualiza o valor de conversão SKAN para você usando um modelo de conversão que você escolhe no painel da Singular).

Para usar SKAdNetwork, não é necessário definir mais nada ou adicionar qualquer código, desde que esteja a usar o SDK mais recente.

Informações adicionais

// Aconteceu um evento de registro
Singular.Event("SignUp");

// Atualize o valor de conversão para 7
SingularSDK.SkanUpdateConversionValue(7);

int? value = SingularSDK.SkanGetConversionValue();

public class Main : MonoBehaviour, SingularConversionValueUpdatedHandler {
  void Awake() {
    SingularSDK.SetConversionValueUpdatedHandler(this);
  }

  void OnConversionValueUpdated(int value) {
    // Use o valor de conversão
  }
}

2.3. Manipulação do consentimento de transparência de rastreio de aplicações iOS (ATT)

Está a apresentar o prompt App Tracking Transparency (ATT)?

A partir do iOS 14.5, os aplicativos devem solicitar o consentimento do usuário (usando a estrutura App Tracking Transparency) antes de poderem acessar e compartilhar alguns dados do usuário, incluindo o IDFA do dispositivo, que é útil para fins de rastreamento.

A Singular e as redes de anúncios beneficiam muito do facto de terem o IDFA para identificar dispositivos e efetuar a atribuição de instalações (embora existam formas de o fazer sem o IDFA). É altamente recomendável solicitar o consentimento do usuário para obter o IDFA.

Recomenda-se atrasar a Inicialização do SDK Singular até que o Utilizador responda ao pedido ATT.

Por defeito, o Singular SDK envia uma sessão de utilizador quando é inicializado. Quando uma sessão é enviada de um novo dispositivo, ela aciona imediatamente o processo de atribuição do Singular - que é realizado com base apenas nos dados disponíveis para o Singular naquele momento. Portanto, é essencial solicitar o consentimento e recuperar o IDFA antes que o SDK da Singular envie a primeira sessão.

Para configurar o waitForTrackingAuthorizationWithTimeoutInterval ajuste a opção de configuração no painel Inspeção de SingularSDKObject . Essa opção define o tempo máximo (em segundos) para que o Singular SDK aguarde o usuário autorizar/negar o AppTrackingTransparency Consent antes de registrar os eventos nos servidores do Singular.

2.4. Manipulação de Deep Links

Deep links são URLs que direcionam os usuários para um conteúdo específico dentro de um aplicativo. Quando um usuário clica em um link profundo em um dispositivo com o aplicativo já instalado, o aplicativo abre e exibe um determinado produto ou experiência.

As ligações de seguimento simples podem incorporar ligações diretas e ligações diretas diferidas. Para obter mais detalhes, consulte as Perguntas frequentes sobre links diretos e as Perguntas frequentes sobre links singulares.

Expanda as seções abaixo para obter detalhes sobre o suporte à plataforma e o código do manipulador:

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

public class SingularMain : MonoBehaviour, SingularLinkHandler
{
    // O Start é chamado antes da atualização do primeiro quadro
    void Start()
    {
        
    }
    
    void Awake () {
        Debug.Log("Singular === Awake");
        /* Registre a classe como o manipulador do Singular Link. Você pode chamar esse método em qualquer ponto da execução do aplicativo. Ele buscará os detalhes do link de rastreamento e chamará OnSingularLnkResolved. */
        SingularSDK.SetSingularLinkHandler(this);
    }
    
    public void OnSingularLinkResolved(SingularLinkParams linkParams) {
        Debug.Log("Singular === OnSingularLinkResolved");
        
        // O destino do deep link, conforme configurado na página Gerenciar links
        string deeplink = linkParams.Deeplink;

        // Os parâmetros de passagem adicionados ao link, se houver.
        string passthrough = linkParams.Passthrough;

        // Se o link está configurado como um deep link diferido.
        bool isLinkDeferred = linkParams.IsDeferred;

        // Adicione o código aqui para processar o deeplink
        Debug.Log("Singular === deeplink: "+deeplink);
        Debug.Log("Singular === passthrough: "+passthrough);
        Debug.Log("Singular === isLinkDeferred: "+isLinkDeferred);      
    }
}

public void SetSingularLinkHandler(SingularLinkHandler 
handler)

public class Main : MonoBehaviour, SingularLinkHandler {
    void Awake () {
        SingularSDK.SetSingularLinkHandler(this)
    }
}

public void OnSingularLinkResolved(SingularLinkParams
linkParams)

public void OnSingularLinkResolved(SingularLinkParams
linkParams){
    // Leia os detalhes do link de rastreamento e registre-os
    Debug.Log("deeplink: " + linkParams.Deeplink);
    Debug.Log("passthrough: " + linkParams.Passthrough);
    Debug.Log("is_deferred: " + linkParams.IsDeferred);
}

public class Main : SingularDeferredDeepLinkHandler {
              
// ...
                
void Awake () {
    // Registre a classe como o manipulador de deep link. 
    // Você pode chamar esse método em qualquer ponto da execução do aplicativo.
    SingularSDK.SetDeferredDeepLinkHandler(this);
}
                
public void OnDeferredDeepLink(string deeplink) {
    // O código para lidar com o deep link fica aqui. 
    // Nesse exemplo, o deep link é apenas registrado.
    Debug.Log ("Deep link received:" + deeplink);
}
                
// ...

2.5. Inicializando o SDK

O código de inicialização do SDK deve ser chamado sempre que seu aplicativo for aberto. Ele é um pré-requisito para todas as funcionalidades de atribuição do Singular e envia uma nova sessão para o Singular, que é usada para calcular a retenção de usuários.

Por padrão, SingularSDK.cs inicializa o SDK automaticamente quando a cena é criada através do método Awake.

Inicialização manual

Se preferir inicializar o SDK manualmente em um ponto posterior da execução do aplicativo, faça o seguinte:

1. Desative a opção Inicializar ao Despertar no painel de inspeção do objeto SingularSDK.
2. Use o método estático SingularSDK.InitializeSingularSDK para inicializar o SDK:

public void InitializeSingularSDK()

// SDK Key e SDK Secret são definidos no
// objeto de jogo associado ao SingularSDK
SingularSDK.InitializeSingularSDK();

2.6. Configurando o tempo limite da sessão (opcional)

Por predefinição, se a aplicação for executada em segundo plano durante 60 segundos ou mais antes de regressar ao primeiro plano, o Singular SDK regista uma nova sessão. É possível alterar o valor de tempo limite padrão modificando a propriedade Session Timeout Sec do seu SingularSDKObject.

2.7. Enviando o ID de usuário para a Singular (opcional)

Você pode enviar seu ID de usuário interno para a Singular usando um método do Singular SDK.

• A ID de usuário pode ser qualquer identificador e não deve expor PII (Informações de identificação pessoal). Por exemplo, não deve utilizar o endereço de correio eletrónico, o nome de utilizador ou o número de telefone de um utilizador. A Singular recomenda o uso de um valor com hash exclusivo apenas para seus dados primários.
• O valor da ID de usuário passado para a Singular também deve ser a mesma ID de usuário interna que você captura em todas as plataformas (Web/Mobile/PC/Console/Offline).
• A Singular incluirá o ID de utilizador nas exportações ao nível do utilizador, ETL e postbacks do BI interno (se configurado). O ID do usuário é um dado primário e a Singular não o compartilha com outras partes.
• Quando definido com o método Singular SDK, o valor da ID de usuário persiste até que seja desinstalado usando o método UnsetCustomUserId ou até que o aplicativo seja desinstalado. Fechar ou reiniciar a aplicação não anula a definição do ID de utilizador.

Para definir o ID de utilizador, utilize o método SetCustomUserId. Para a anular (por exemplo, se o Utilizador "sair" da conta), ligue para UnsetCustomUserId.

Se você já souber a ID de usuário quando o aplicativo for aberto, chame SetCustomUserId antes de inicializar o SDK do Singular. Dessa forma, o Singular pode obter a ID de usuário desde a primeira sessão. No entanto, a ID de usuário normalmente não está disponível até que o usuário se registre ou faça um login. Nesse caso, chame SetCustomUserId após a conclusão do fluxo de registo.

SingularSDK.SetCustomUserId("custom_user_id");

SingularSDK.UnsetCustomUserId();

SingularSDK.SetDeviceCustomUserId('CustomUserId');

3. Rastreamento de eventos e receita

3.1. Rastreamento de eventos (não receita)

A Singular pode coletar dados sobre eventos in-app para ajudar a analisar o desempenho de suas campanhas e medir KPIs. Por exemplo, a sua organização pode querer recolher dados sobre logins de utilizadores, registos, conclusões de tutoriais ou subida de nível numa aplicação de jogos.

O Singular suporta uma variedade de eventos padrão. As redes de anúncios geralmente suportam esses eventos comumente usados para relatórios e otimização. Outra vantagem é que, quando você usa nomes de eventos padrão, o Singular os reconhece automaticamente e os adiciona à lista Eventos sem que você precise defini-los manualmente. Recomendamos o uso de eventos padrão sempre que possível.

A lista de eventos enviados para a Singular (com os atributos que os acompanham) deve ser compilada pela equipa de UA/marketing/negócio com base nos KPIs de marketing da sua organização. A equipe de negócios pode seguir Como rastrear eventos no aplicativo: Guia para clientes de atribuição singular.

Com cada evento que você rastreia, você pode passar vários atributos. Veja os atributos padrão recomendados por evento.

Envie eventos padrão para a Singular usando os métodos event ou eventWithArgs em seu código.

SingularSDK.Event(Events.sngLogin);

public static void Event(string name)

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

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

// 1) Enviar o evento padrão Login
SingularSDK.Event(Events.sngLogin);

// 2) Um exemplo de evento personalizado que passa dois pares de valores-chave
SingularSDK.Event("myEventName", "Key1", "Value1", "Key2", 1234);

// 3) Um exemplo de evento JSON passando um dicionário
// Criar um dicionário para atributos
Dictionary<string, object> attributes = new Dictionary<string, object>();

// Adicionar atributos
attributes["key1"] = "value1";
attributes["key2"] = "value2";
attributes["key3"] = "value3";
// Adicione mais atributos conforme necessário

SingularSDK.Event(attributes, "myEventName");

3.2. Rastreamento de receita

A Singular pode recolher dados sobre a receita obtida através da aplicação para ajudar a analisar o desempenho e o ROI das suas campanhas. O Singular disponibilizará os dados em relatórios, exportação de logs e postbacks.

Você pode rastrear eventos de receita usando o objeto IAP (In-App Purchases) integrado do Unity. Dessa forma, Singular obtém todas as informações disponíveis sobre a compra para relatórios mais completos. O Singular também obtém o recibo de compra, que o Singular usa no back-end para validar a compra e descartar fraudes de atribuição.

public static void InAppPurchase(Product product,
Dictionary<string, object> attributes, bool isRestored = false)

public static void InAppPurchase(string eventName,
Product product, Dictionary<string, object> attributes, 
bool isRestored = false)

public static void InAppPurchase(IEnumerable<Product> products,
Dictionary<string, object> attributes, bool isRestored = false)

public static void InAppPurchase(string eventName,
IEnumerable<Product> products, Dictionary<string, object> 
attributes, bool isRestored = false)

// IAP com um único produto e sem atributos adicionais
SingularSDK.InAppPurchase(myProduct, null);

// IAP com um único produto e atributos
var attr = new Dictionary<string, object>() {
["my_first_attribute"] = "value1",
["my_second_attribute"] = "value2"};
 
SingularSDK.InAppPurchase(myProduct, attr);

// IAP com um único produto, sem atributos extras e com um nome de evento personalizado

SingularSDK.InAppPurchase("MyCustomProduct",
myProduct, null);

// IAP com lista de produtos, sem atributos adicionais
SingularSDK.InAppPurchase(myProductList, null);

// IAP com uma lista de produtos, sem atributos extras e com um nome de evento personalizado

SingularSDK.InAppPurchase("MyCustomProducts",
myProductList, null);

public static void Revenue(string currency, double amount)

public static void Revenue(string currency, double amount, string productSKU, string productName, string productCategory, int productQuantity, double productPrice)

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

// Enviar um evento de receita sem detalhes do produto
SingularSDK.Revenue("USD", 1.99);

// Enviar um evento de receita com detalhes do produto
SingularSDK.Revenue("USD", 4.99, "coin_package_abc123", "Coin Pack 5", "Bundles", 1, 4.99);

// Enviar um evento de receita com o JSON Dictionary para atributos
Dictionary<string, object> attributes = new Dictionary<string, object>();

// Adicionar atributos
attributes["productSKU"] = "coin_package_abc123";
attributes["productName"] = "Coin Pack 5";
attributes["productCategory"] = "Bundles";
attributes["productQuantity"] = 2;
attributes["productPrice"] = 4.99;

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

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

public static void CustomRevenue(string eventName, string currency, double amount, string productSKU, string productName, string productCategory, int productQuantity, double productPrice)

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

// Enviar um evento de receita com um nome personalizado
SingularSDK.CustomRevenue("MyCustomRevenue", "USD", 9.99);

// Enviar um evento de receita com um nome personalizado + detalhes do produto
SingularSDK.CustomRevenue("MyCustomRevenue", "USD", 50.50, "abc123", "myProductName", "myProductCategory", 2, 25.50);

// Enviar um evento de receita com um nome personalizado + Dicionário JSON para atributos
// Criar um dicionário para atributos
Dictionary<string, object> attributes = new Dictionary<string, object>();

// Adicionar atributos
attributes["productSKU"] = "coin_package_abc123";
attributes["productName"] = "Coin Pack 5";
attributes["productCategory"] = "Bundles";
attributes["productQuantity"] = 2;
attributes["productPrice"] = 4.99;
// Adicione mais atributos conforme necessário

SingularSDK.CustomRevenue("MyCustomRevenue", "USD", 9.98, attributes);

3.3. Rastreamento de evento híbrido (avançado)

A Singular recomenda o envio de todos os eventos e receitas por meio do SDK da Singular integrado ao seu aplicativo. No entanto, a Singular pode coletar eventos e receitas de outras fontes.

Qualquer evento NÃO enviado do SDK da Singular deve estar em conformidade com os requisitos de documentação de eventos de servidor para servidor da Singular e fornecer o identificador de dispositivo correspondente para atribuir corretamente um evento.

Guias de rastreamento de eventos híbridos

4. Opções avançadas

4.1. Criação de links curtos de referência

Use links curtos para transformar Links Singulares longos e cheios de parâmetros em links mais curtos e mais seguros que são convenientes para compartilhamento.

Normalmente, pretende criar ligações curtas de forma dinâmica para que os utilizadores da sua aplicação possam partilhá-las com amigos para os convidar a utilizar a aplicação.

Para criar um link curto, você precisa de:

• Um link singular que leva ao download do seu aplicativo (consulte as Perguntas frequentes sobre links singulares).
• Você pode adicionar qualquer parâmetro que desejar ao link dinamicamente (consulte Parâmetros de link de rastreamento para obter a lista de opções).
• Se quiser rastrear as novas instalações de aplicativos até o usuário que compartilhou o link, você deverá fornecer o Nome do referenciador e a ID do referenciador do usuário que fez a referência.

Use o método createReferrerShortLink para criar um link curto, como no exemplo abaixo.

void callback(string shortLinkURL, string error){
    // Adicione sua lógica de compartilhamento aqui se shortLinkURL não for nulo 
    // Se houver um erro, adicione lógica para tentar novamente/abortar/modificar os parâmetros
    // passados para a função, com base na causa do erro
}

SingularSDK.createReferrerShortLink(
    "https://sample.sng.link/B4tbm/v8fp?_dl=https%3A%2F%2Fabc.com",
    "John Doe", // Nome do referenciador
    "342", // ID do referenciador
    new Dictionary<string, string>() { 
        // um objeto Dictionary que contém todos os parâmetros que você deseja adicionar
        {"channel", "sms"}
    },
    callback 
);

4.2. Adicionando suporte à atribuição de receita de anúncios

4.3. Acompanhamento de desinstalações

Rastreamento de desinstalação do Android

Para ativar o rastreamento de desinstalação para seu aplicativo Android, primeiro configure o aplicativo na plataforma Singular conforme detalhado em Configuração do rastreamento de desinstalação. Em seguida, siga as instruções abaixo.

Como ativar o rastreamento de desinstalação usando o Firebase Cloud Messaging (FCM):

1. Integrar com o FCM:

Para rastrear desinstalações, você pode usar os serviços da plataforma Firebase Cloud Messaging (FCM). Se você ainda não estiver usando o FCM, siga as instruções do Google sobre como Configurar um aplicativo cliente do Firebase Cloud Messaging no Android.

2. Atualizar o arquivo AndroidManifest.xml:

Actualize o seu ficheiro AndroidManifest.xml para adicionar o filtro de intenção necessário para a sua aplicação (substitua MyFirebaseMessagingService pela sua classe que implementa o Serviço Firebase):

<service android:name=".java.MyFirebaseMessagingService" android:exported="false">
  <intent-filter>
    <action android:name="com.google.firebase.MESSAGING_EVENT" />
  </intent-filter> 
</service>

3. Registar e enviar o token de dispositivo FCM:

Depois de recuperar o token FCM, passe-o como parâmetro para o método 'RegisterTokenForUninstall':

SingularSDK.RegisterTokenForUninstall(String fcmDeviceToken);

O método 'RegisterTokenForUninstall' deve ser chamado antes dométodo 'SingularSDK.InitializeSingularSDK()'.

Controlo de desinstalação do iOS

O rastreamento de desinstalação no iOS é baseado na tecnologia de notificação push da Apple. Se a sua aplicação não suportar notificações push, consulte o guia da Apple. Se a sua aplicação já suporta notificações push, tem de passar o token de dispositivo devolvido pelo APNS utilizando o método RegisterTokenForUninstall depois de o SDK ser inicializado.

public static void RegisterTokenForUninstall
(string APNSToken)

// passar o token APNS como uma string hexadecimal 
  SingularSDK.RegisterTokenForUninstall("ba85ab31a7c7
f5c2f012587f29fb0e596d4b67e7b7b2838fa1a8582c1f7dbdee");

4.4. Adicionando propriedades globais

A cada sessão e evento enviado pelo aplicativo, o Singular SDK permite definir propriedades adicionais personalizadas para enviar aos servidores Singular. Essas propriedades podem representar qualquer informação que você queira sobre o usuário, o modo do aplicativo, o status ou qualquer outra coisa. Depois de definir essas propriedades, elas ficam disponíveis como dimensões em seus relatórios e você pode usá-las para dividir seus dados.

Por exemplo, se tiver uma aplicação de jogos, pode definir uma propriedade chamada "Nível" e defini-la inicialmente como "0". Qualquer sessão e evento enviado da aplicação será enviado com "Nível": "0". Quando o utilizador subir de nível, a propriedade é reposta a "1" e assim sucessivamente. Pode então obter os seus relatórios, incluindo sessões, contagens de eventos e dados de receitas, repartidos por nível de utilizador.

Definindo propriedades globais antes da inicialização

É possível usar o método SetGlobalProperty para definir propriedades globais através do SingularSDK antes de inicializar o SDK. Se quiser que suas propriedades globais sejam incluídas na sessão, desative o sinalizador 'Initialize On awake'.

Como as propriedades globais e seus valores persistem entre as execuções do aplicativo, a propriedade que você está definindo pode já estar definida com um valor diferente. Use o parâmetro overrideExisting para informar ao SDK se deve substituir uma propriedade existente pelo novo valor.

Definir propriedades globais após a inicialização

É possível usar os seguintes métodos para definir, cancelar a definição e recuperar propriedades globais a qualquer momento durante a execução do aplicativo.

bool result = SingularSDK.SetGlobalProperty("key", "value", false);

Dictionary<string, string> props = SingularSDK.GetGlobalProperties();

SingularSDK.UnsetGlobalProperty(“test_key”);

SingularSDK.clearGlobalProperties();

4.5. Coletando o referenciador de instalação em dispositivos Android mais antigos

No Android, o referenciador de instalação é a ferramenta mais precisa da Singular para determinar a atribuição e ajudar a Singular a detetar e analisar tentativas de fraude. É um identificador fornecido pela Google Play Store que aponta para o anúncio no qual o usuário clicou antes de instalar o aplicativo.

Em dispositivos com a versão mais recente da Google Play Store, o SDK da Singular coleta automaticamente o valor do referenciador de instalação (já que a Singular está integrada à API de referenciador mais recente da Google Play).

Para coletar o referenciador de instalação em dispositivos mais antigos, siga as instruções no guia do SDK do Android.

5. Conformidade com as leis de privacidade de dados

5.1. Limitar a partilha de dados

A Singular fornece uma funcionalidade de proteção da privacidade para o ajudar a cooperar com quaisquer parceiros que possam estar em conformidade com as leis de privacidade do consumidor, como o GDPR e o CCPA(California Consumer Privacy Act). Estes parceiros pretendem ser notificados se o utilizador final tiver consentido a partilha das suas informações privadas.

Limitar a partilha de dados

Se você implementou uma maneira de pedir o consentimento dos usuários para compartilhar suas informações, use o método limitDataSharing para notificar a Singular sobre a escolha do usuário:

• Utilize limitDataSharing:NO para indicar que o utilizador consentiu (optou por participar) na partilha das suas informações.
• Utilize limitDataSharing:YES se o utilizador não deu o seu consentimento.

A Singular utiliza LimitDataSharing em"Postbacks de privacidade do utilizador" e transmite esta informação a parceiros que a exigem para cumprir os regulamentos relevantes. Consulte"Privacidade do utilizador e Limitar partilha de dados" para obter mais informações.

// O usuário optou por compartilhar dados
SingularSDK.LimitDataSharing(false);

5.2. Métodos adicionais para conformidade com o GDPR

O Singular SDK fornece vários métodos para ajudá-lo a cumprir as políticas do GDPR e permitir que a Singular saiba sobre o consentimento ou não consentimento do usuário para rastreamento.

SingularSDK.TrackingOptIn();

SingularSDK.StopAllTracking();

SingularSDK.ResumeAllTracking();

SingularSDK.IsAllTrackingStopped();