SDK do Unity - Integração básica

Documento

Pré-requisitos

Conclua estas etapas de pré-requisitos antes de instalar o SDK do Singular Unity para garantir um processo de integração tranquilo.

Pré-requisitos necessários:


Instalação

Instalação através do Unity Package Manager (UPM)

O Singular SDK do Unity é instalado através do Unity Package Manager usando URLs do Git. Siga estas etapas para adicionar o SDK ao seu projeto.

Etapas de instalação

  1. Abra o Gerenciador de pacotes: Em Unity, navegue até Janela > Gerenciador de pacotes.
  2. Adicionar pacote do Git: Clique no botão [+]no canto superior esquerdo e selecione "Add package from git URL".
  3. Introduza o URL do Git:
    • Para SDK padrão: Introduza https://github.com/singular-labs/Singular-Unity-SDK.git
    • Para o SDK para crianças: Digite https://github.com/singular-labs/Singular-Unity-SDK.git#kids
  4. Concluir a instalação: Clique em "Adicionar"para instalar o pacote SDK.

Não está a utilizar o Google EDM4U? Se o seu projeto não utiliza o External Dependency Manager, tem de transferir e adicionar manualmente as dependências nativas.

Instalação manual de dependências

  1. Baixe as dependências: Baixe o arquivo Plugins.zip apropriado do bucket S3 da Singular:
  2. Extrair para Assets: Extraia os ficheiros descarregados e mova-os para Assets > Plugins no seu projeto Unity.
  3. Configurar a estrutura iOS: Navegue até Assets > Plugins > iOS e selecione Singular.xcframework.
  4. Incorporar o binário: No painel Inspetor, selecione a opção "Add to Embedded Binaries".

Dicas de configuração do Android

Configure as definições de compilação do Android para garantir a funcionalidade adequada do SDK. O Unity fornece várias formas de personalizar os manifestos do Android e os ficheiros Gradle.

Como atualizar AndroidManifest.xml
#

Você pode modificar o AndroidManifest usando um de dois métodos:

Método 1: Manifesto personalizado do Unity

  1. Navegue até Arquivo > Configurações de compilação > Configurações do jogador > Configurações de publicação.
  2. Active "Manifesto principal personalizado" na secção Definições de publicação.
  3. O Unity gera um arquivo AndroidManifest.xmlpadrão em Assets/Plugins/Android/AndroidManifest.xml.
  4. Edite este ficheiro para adicionar as permissões e configurações necessárias.

Fonte: Documentação do manifesto do Android do Unity

Método 2: Android Studio

  1. Exporte seu projeto do Unity usando Arquivo > Configurações de compilação > Exportar projeto.
  2. Abra o projeto exportado no Android Studio.
  3. Edite o arquivo AndroidManifest.xml diretamente no Android Studio.
Como atualizar os ficheiros de compilação do Gradle
#

Método 1: Modelo personalizado do Unity

  1. Navegue até File > Build Settings > Player Settings > Publishing Settings.
  2. Active "Custom Gradle Template" (Modelo Gradle Personalizado ) na secção Publishing Settings (Definições de Publicação).
  3. O Unity gera um ficheiro mainTemplate.gradle em Assets/Plugins/Android/mainTemplate.gradle.
  4. Adicione as suas configurações Gradle personalizadas a este ficheiro.

Fonte: Documentação de visão geral do Unity Gradle

Método 2: Android Studio

  1. Exporte o seu projeto do Unity.
  2. Abra o projeto no Android Studio.
  3. Editar diretamente o ficheiro build.gradle da aplicação.
Resolver erros de classes duplicadas
#

Ao criar aplicativos Android no Unity, você pode encontrar erros de "Duplicate class" causados por várSDK do iOSs incluindo as mesmas dependências transitivas. Isso geralmente ocorre com a biblioteca Android Vending Licensing ao usar o AppLovin SDK e o Singular SDK.

Exemplo de erro:

Duplicate class com.android.vending.licensing.ILicensingService found in modules 
applovin-sdk-13.5.0.aar -> jetified-applovin-sdk-13.5.0-runtime (com.applovin:applovin-sdk:13.5.0) 
and singular_sdk-12.10.0.aar -> jetified-singular_sdk-12.10.0-runtime (com.singular.sdk:singular_sdk:12.10.0)

Solução 1: Usando o Gerenciador de Dependências Externas (EDM4U)

Se o seu projeto usa o Gerenciador de Dependências Externas para Unity (recomendado), adicione regras de exclusão ao seu arquivo XML de Dependências.

  1. Localize o seu ficheiro *Dependencies.xml no seu projeto Unity (normalmente em Assets/Editorou numa localização semelhante).
  2. Adicione uma regra de exclusão a uma das dependências do SDK:
XML
<dependencies>
  <androidPackages>
    <androidPackage spec="com.applovin:applovin-sdk:13.5.0">
      <androidSdkPackageIds>
        <exclude group="com.android.vending" module="licensing"/>
      </androidSdkPackageIds>
    </androidPackage>
    <androidPackage spec="com.singular.sdk:singular_sdk:12.10.0" />
  </androidPackages>
</dependencies>

Observação: essa abordagem é mais persistente do que modificar os modelos do Gradle, pois o Android Resolver pode substituir as alterações de modelos personalizados durante a resolução.

Solução 2: usar modelos personalizados do Gradle

Se não estiver a utilizar o EDM4U, aplique regras de exclusão diretamente nos seus ficheiros de configuração do Gradle.

  1. Navegue até Arquivo > Configurações de compilação > Configurações do player > Configurações de publicação.
  2. Active "Modelo de Gradle principal personalizado"ou "Modelo de Gradle do lançador personalizado".
  3. Abra Assets/Plugins/Android/mainTemplate.gradle(ou launcherTemplate.gradle).
  4. Adicione a regra de exclusão ao seu bloco de dependências:
Gradle
dependencies {
    implementation('com.applovin:applovin-sdk:13.5.0') {
        exclude group: 'com.android.vending', module: 'licensing'
    }
    implementation 'com.singular.sdk:singular_sdk:12.10.0'
}

Alternativa: Aplique uma exclusão global adicionando isso após o bloco de dependências:

Gradle
configurations.all {
    exclude group: 'com.android.vending', module: 'licensing'
}

Verificar resolução

  1. Depois de aplicar a exclusão, limpe o seu projeto eliminando as pastas Library/Bee e Temp.
  2. Reconstrua seu projeto Android no Unity.
  3. Verifique se o erro de classe duplicada não aparece mais na saída da compilação.

Por que isso funciona: Ambos os SDKs agrupam a mesma biblioteca de licenciamento do Android como uma dependência transitiva. A exclusão diz ao Gradle para usar apenas uma cópia, resolvendo o conflito.

Configuração do ProGuard
#

Se o seu projeto usa o ProGuard para ofuscação de código, adicione as seguintes regras de manutenção ao seu arquivo proguard-unity.txt para evitar que o SDK Singular seja removido:

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

Dicas de configuração do iOS

Defina as configurações específicas do iOS para habilitar a atribuição adequada, a vinculação profunda e a funcionalidade de teste.

Atualizar as dependências do CocoaPods
#

Depois de criar seu projeto Unity para iOS e antes de criar no Xcode, atualize as dependências do CocoaPods para garantir que você tenha as versões mais recentes do SDK.

Terminal
cd /path/to/your/ios/project
pod repo update
pod update
Registar o IDFV para testes
#

Para testar sua integração, registre o IDFV (Identifier for Vendor) para adicionar rapidamente seu dispositivo de teste no Console do Singular SDK.

Adicionar registro de IDFV

  1. Abra seu projeto Xcode após a compilação do Unity.
  2. Navegue até Classes > UnityAppController.mm.
  3. Encontre o método applicationDidBecomeActive.
  4. Adicione o seguinte código para registar o IDFV:
Objective-C
// Log IDFV for testing
NSLog(@"Singular === IDFV: %@", [[[UIDevice currentDevice] identifierForVendor] UUIDString]);
  1. Compile e execute seu aplicativo no Xcode.
  2. Verifique os logs do console do Xcode para a saída do IDFV.
  3. Copie o IDFV e adicione-o como um dispositivo de teste no Console do Singular SDK.
Configurar suporte a Deep Link
#

Habilite Universal Links para links diretos configurando Domínios associados no seu projeto Xcode.

  1. Adicionar domínio associado: No Xcode, navegue até a guia Assinatura e recursosdo seu aplicativo de destino.
  2. Habilite a capacidade: Clique em [+] Capacidade e adicione "Domínios associados".
  3. Adicionar domínio: Adicione seu domínio de rastreamento Singular no formato: applinks:yourdomain.sng.link
  4. Configurar ID da equipe: No painel do Singular, navegue até as configurações do seu aplicativo e adicione seu ID da equipe da Apple. Isso permite que o Singular gere e hospede o arquivo Apple App Site Association (AASA) necessário para os Universal Links.

Importante: Sem Domínios Associados e ID de Equipe configurados corretamente, os Universal Links não funcionarão e os usuários não poderão abrir seu aplicativo a partir de links de rastreamento do Singular.


Integrar o SDK

Criar o GameObject SingularSDK

O Singular SDK requer um GameObject na hierarquia da sua cena Unity para funcionar. Você pode adicionar este GameObject usando o prefab fornecido ou criando-o manualmente.

Método 1: Usar o Prefab Singular (Recomendado)
#

Adicionar Prefab à cena

  1. No painel Projeto, navegue até Pacotes > Singular > SingularSDK > Prefabs.
  2. Arraste o prefab SingularSDKObject para o painel Hierarquia.
  3. O prefab está agora pronto para ser configurado no Inspetor.
Método 2: Criar GameObject manualmente
#

Criação manual de GameObject

  1. No painel Hierarchy (Hierarquia ), clique com o botão direito do rato e selecione Create Empty (Criar vazio).
  2. Dê um nome ao GameObject SingularSDKObject (é necessário um nome exato).
  3. Com o GameObject selecionado, navegue até o painel Inspetor.
  4. Clique em Adicionar componente.
  5. Procure por "Singular" e selecione o componente de script Singular SDK.

Crítico: O GameObject deve ter o nome exato SingularSDKObject para que o SDK funcione corretamente.

Configurar as definições do SDK

Configure as credenciais do SDK e as definições de inicialização através do Unity Inspetor. Sua chave de API e segredo são necessários para que o SDK se comunique com os servidores da Singular.

Adicionar credenciais de API

  1. Selecione SingularSDKObject: Clique no SingularSDKObject na sua Hierarquia.
  2. Localize as credenciais: Faça login na sua conta Singulare navegue até Developer Tools > Integração do SDK > Chaves do SDK.
  3. Copiar chaves: Copie a chave SDK e o segredo SDK.
  4. Cole no Inspetor: No painel Inspetor do Unity, cole as credenciais nos campos Singular API Key e Singular API Secret.

Importante: NÃO use a chave da API de relatório Singular, use apenas a chave e o segredo da API específicos do SDK na página Integração do SDK. O uso de credenciais erradas impedirá que os dados sejam enviados para o Singular.

Verificar sua integração: Após a configuração, teste sua implementação usando o Singular SDK Consolepara garantir que os eventos estão sendo rastreados corretamente.

Configurações padrão do inspetor

O SingularSDKObject vem com padrões sensatos. Entender essas configurações ajuda a personalizar o comportamento do SDK de acordo com os requisitos do seu aplicativo.

Opções de configuração padrão
#
  • Inicializar ao acordar: Ativado por predefinição. O SDK é inicializado automaticamente quando o GameObject acorda. Desactive esta opção se precisar de atrasar a inicialização devido a consentimento de privacidade ou outros requisitos.
  • SKAN ativado: Ativado por padrão (somente iOS). Ativa a atribuição de SKAdNetwork no Modo gerenciado, em que o Singular atualiza automaticamente os valores de conversão com base no modelo de conversão configurado.
  • Aguardar autorização de rastreamento: Defina como 0 (desativado). Se o seu aplicativo mostrar o prompt iOS App Tracking Transparency (ATT), defina isso como 300 segundos. Isso atrasa a sessão SDK até que o usuário responda ao prompt ATT, garantindo que o IDFA possa ser capturado se o consentimento for concedido. Deixe em 0 se não estiver a utilizar a ATT.
  • Ativar o registo: Ativado por predefinição. Emite registos de depuração do SDK para ajudar na integração e na resolução de problemas. Deve ser desativado em compilações de produção. Funciona com a definição de Nível de registo (ver abaixo).
  • Nível de registo: Definido como 3 (Info) por predefinição. Controla a verbosidade do registo. Números mais baixos produzem registos mais detalhados:
    C#
    // Based on Android Logger log levels
    public enum LogLevel {
       Verbose = 2,  // Most verbose
       Debug   = 3,
       Info    = 4,  // Default
       Warn    = 5,
       Error   = 6,
       Assert  = 7   // Least verbose
    }

    Nota: Os registos detalhados estão disponíveis principalmente no Android.

  • DDL Timeout Sec: Defina como 0 (usa o padrão de 60 segundos). Determina quanto tempo o SDK espera por dados de deep link adiados do servidor. O servidor para de pesquisar após esse tempo limite se nenhum deep link diferido for encontrado.
  • Tempo limite da sessão Seg: Definido como 0 (usa o padrão de 60 segundos). Define por quanto tempo o aplicativo pode ficar em segundo plano antes que o SDK crie uma nova sessão ao retornar ao primeiro plano.
  • Tempo limite de resolução de link curto: Definido como 0 (usa o padrão de 10 segundos). Protege a experiência do utilizador ao evitar longas esperas se uma ligação curta não puder ser resolvida.

Opções de configuração adicionais

Configuração de instalação do referenciador do Facebook (Meta)
#

A partir de 18 de junho de 2025: A Medição móvel avançada (AMM)do Meta elimina a necessidade de implementar o Referenciador de instalação do Meta. Se o relatório AMM estiver ativado, não será necessário configurar o Referenciador de instalação do Meta.

Se você precisar oferecer suporte ao método legado de atribuição do Meta Install Referrer, adicione sua ID do aplicativo do Facebook à configuração SingularSDKObject.

Etapas de configuração

  1. Selecione o SingularSDKObject na hierarquia da cena.
  2. No painel Inspetor, localize o campo "ID do aplicativo do Facebook".
  3. Insira sua ID de aplicativo do Facebook (encontre-a no Console do desenvolvedor do Facebook).

Recursos adicionais:


Inicializar o SDK

Conformidade com a privacidade: Ao implementar o Singular SDK, cumpra as leis de privacidade em suas regiões operacionais, incluindo GDPR, CCPA, COPPA e outras. Para obter orientação, consulte Práticas de aceitação e exclusão do SDK.

Inicialize o SDK Singular sempre que seu aplicativo for iniciado. A inicialização do SDK é essencial para todas as funcionalidades de atribuição do Singular e cria uma nova sessão para calcular as métricas de retenção de usuários.

Inicialização automática

Por padrão, o script SingularSDK.cs inicializa automaticamente o SDK quando sua cena é carregada através do método Awake() do Unity. Nenhum código adicional é necessário se a opção Inicializar ao acordarestiver ativada no Inspetor.

Inicialização manual

Se precisar de inicializar o SDK num momento específico (por exemplo, depois de obter o consentimento do utilizador), desactive a inicialização automática e chame o método de inicialização manualmente.

Configuração da inicialização manual

  1. Selecione o objeto SingularSDKObject na hierarquia da cena.
  2. No painel Inspetor, desmarque Inicializar ao acordar.
  3. Chame SingularSDK.InitializeSingularSDK() no seu código quando estiver pronto para inicializar.

Método InitializeSingularSDK

Use este método para inicializar manualmente o SDK quando a inicialização automática estiver desativada.

C#
using UnityEngine;
using Singular;

public class GameInitializer : MonoBehaviour
{
    void Start()
    {
        // Perform any required setup (e.g., consent management)
        CheckUserConsent();

        // Initialize Singular SDK after consent is obtained
        // SDK Key and Secret are configured on the SingularSDKObject
        SingularSDK.InitializeSingularSDK();
    }

    void CheckUserConsent()
    {
        // Your consent logic here
    }
}

Segurança de thread: Sempre chame os métodos do Singular SDK do Unity a partir do mesmo thread usado para outras chamadas da API do Unity. O SDK não é seguro para threads em vários threads.


Configuração avançada

Configurar o tempo limite da sessão

Personalize o tempo que seu aplicativo pode permanecer em segundo plano antes que o SDK crie uma nova sessão quando o aplicativo retornar ao primeiro plano.

Configuração do tempo limite da sessão

O tempo limite de sessão padrão é de 60 segundos. Para alterar esse valor:

  1. Selecione o objeto SingularSDKObject na hierarquia da cena.
  2. No painel Inspetor, localize o campo Session Timeout Sec.
  3. Digite o valor de tempo limite desejado em segundos (por exemplo, 120 para 2 minutos).
  4. Deixe em 0 para usar o tempo limite padrão de 60 segundos.

Melhores práticas: Considere os padrões de utilização típicos da sua aplicação ao definir o tempo limite da sessão. Os jogos com sessões curtas frequentes podem beneficiar de um tempo limite mais curto, enquanto as aplicações de produtividade podem necessitar de tempos limite mais longos.


Atualizando de .unitypackage para UPM

Se você estiver migrando do método de instalação legado .unitypackage para a abordagem moderna do Unity Package Manager (UPM), siga estas etapas críticas de atualização.

Instruções de migração: .unitypackage para UPM
#

Crítico: Você deve remover manualmente todos os arquivos do Singular SDK existentes antes de instalar o pacote UPM. Se isso não for feito, haverá conflitos e erros de compilação.

Procedimento de atualização

Conclua estas etapas em ordem antes de instalar o SDK por meio do Unity Package Manager:

Remoção de arquivos passo a passo
#

1. Remover ficheiros de código

Navegue até a pasta /Codedo seu projeto (normalmente Assets/Singular/Code) e exclua todos os scripts C# relacionados ao Singular.

2. Remover dependências do Android

Navegue até /Plugins/Androide remova os seguintes arquivos Singular:

  • Todos os ficheiros .aar com "singular" no nome
  • Todos os ficheiros .jar com "singular" no nome
  • singular-sdk.aar
  • install-referrer-*.aar
  • singular-unitybridge.aar

3. Remover as dependências do iOS

Navegue até /Plugins/iOS e remova os seguintes ficheiros Singular:

  • Todos os ficheiros de cabeçalho .h (por exemplo, SingularSDK.h)
  • Todos os ficheiros de implementação .m (por exemplo, SingularUnityBridge.m)
  • Singular.xcframework pasta

Importante: Remova apenas os ficheiros específicos do Singular. Tenha cuidado para não excluir outros arquivos de plug-in dos quais seu projeto possa depender.

4. Verificar o estado limpo

  1. Depois de remover os arquivos, feche o Unity completamente.
  2. Exclua a pasta Library no diretório do seu projeto para forçar o Unity a reimportar os assets.
  3. Reabra seu projeto Unity.
  4. Aguarde até que o Unity termine de reimportar os recursos.
  5. Verifique se não há erros de compilação antes de continuar com a instalação do UPM.

5. Instalar o pacote UPM

Agora você está pronto para instalar o Singular SDK através do Unity Package Manager. Siga as instruções de instalação do UPMna parte superior deste guia.