Baixar SDK do Android versão 12.14.0

Vídeo guia disponível

Assista a este vídeo para um tutorial detalhado do processo de integração. Para obter os melhores resultados, utilize tanto o vídeo quanto o guia escrito abaixo.

Pré-requisitos

Conclua as etapas em Integração do SDK da Singular: planejamento e pré-requisitos antes de prosseguir com esta integração.

Importante: Essas etapas de pré-requisitos são obrigatórias para qualquer integração do SDK da Singular.

Instalação

Métodos de instalação

Nota: O Android Studio agora usa, por padrão, Kotlin DSL (build.gradle.kts) para novos projetos. Todos os exemplos de código abaixo mostram os formatos Kotlin DSL (recomendado) e Groovy DSL .

Método 1: Gradle (recomendado)

Adicionar repositório do SDK

Configure o repositório Maven da Singular no gerenciamento de dependências do seu projeto.

Nota: A partir do Gradle 7, o Android recomenda usar declarações de repositório centralizadas em settings.gradle ou settings.gradle.kts em vez de declarações em build.gradle no nível do projeto ou do módulo.

Configuração para Gradle 7+

Adicione o repositório do SDK da Singular ao seu arquivo de settings:

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven {
            url = uri("https://maven.singular.net/")
        }
    }
}

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven {
            url 'https://maven.singular.net/'
        }
    }
}

Versões mais antigas do Gradle

Para versões mais antigas do Gradle, adicione o repositório ao arquivo de build em nível de projeto:

repositories {
    mavenCentral()
    maven {
        url = uri("https://maven.singular.net/")
    }
}

repositories {
    mavenCentral()
    maven {
        url 'https://maven.singular.net/'
    }
}

Adicionar a dependência da biblioteca da Singular

Adicione a biblioteca da Singular às dependências do módulo do seu aplicativo.

dependencies {
    implementation("com.singular.sdk:singular_sdk:12.14.0")
}

dependencies {
    implementation 'com.singular.sdk:singular_sdk:12.14.0'
}

Solução de problemas: classes duplicadas

Você pode encontrar erros de classes duplicadas quando várias dependências incluem a mesma biblioteca. Isso ocorre normalmente com as bibliotecas do Google Play Services ao usar versões mais antigas.

Exemplo de erro comum:

Duplicate class com.google.android.gms.common.api.ResultCallback found in modules play-services-6.5.87.aar and play-services-basement-17.6.0.aar

Solução: excluir as dependências conflitantes

Para resolver problemas de classes duplicadas, exclua a dependência transitiva conflitante do SDK da Singular ou das demais dependências que causam o conflito.

dependencies {
    // Exclude specific Google Play Services modules from Singular SDK
    implementation("com.singular.sdk:singular_sdk:12.14.0") {
        exclude(group = "com.google.android.gms", module = "play-services")
    }

    // Add the specific Google Play Services libraries your app needs
    implementation("com.google.android.gms:play-services-ads-identifier:17.0.0")
    implementation("com.google.android.gms:play-services-appset:16.0.2")
}

dependencies {
    // Exclude specific Google Play Services modules from Singular SDK
    implementation('com.singular.sdk:singular_sdk:12.14.0') {
        exclude group: 'com.google.android.gms', module: 'play-services'
    }

    // Add the specific Google Play Services libraries your app needs
    implementation 'com.google.android.gms:play-services-ads-identifier:17.0.0'
    implementation 'com.google.android.gms:play-services-appset:16.0.2'
}

Regras globais de exclusão

Se o conflito de classes duplicadas afetar várias dependências no seu projeto, você pode aplicar uma regra global de exclusão.

configurations.all {
    exclude(group = "com.google.android.gms", module = "play-services")
}

configurations.all {
    exclude group: 'com.google.android.gms', module: 'play-services'
}

Verificação da resolução de dependências

Após aplicar as regras de exclusão, verifique a árvore de dependências para garantir que os conflitos foram resolvidos.

./gradlew app:dependencies --configuration debugRuntimeClasspath

Este comando exibe a árvore completa de dependências do seu aplicativo, mostrando quais bibliotecas estão incluídas e quais foram excluídas.

Suporte à Samsung Galaxy Store

Adicione a dependência do install referrer da Samsung Galaxy Store se seu aplicativo for distribuído pela Samsung Galaxy Store.

dependencies {
    implementation("store.galaxy.samsung.installreferrer:samsung_galaxystore_install_referrer:4.0.0")
}

dependencies {
    implementation 'store.galaxy.samsung.installreferrer:samsung_galaxystore_install_referrer:4.0.0'
}

Dependências transitivas

Se você desativou as dependências transitivas para o SDK da Singular, adicione manualmente estas bibliotecas obrigatórias às dependências do módulo do aplicativo.

dependencies {
    implementation("com.android.installreferrer:installreferrer:2.2")
    implementation("com.google.android.gms:play-services-appset:16.0.2")
}

dependencies {
    implementation 'com.android.installreferrer:installreferrer:2.2'
    implementation 'com.google.android.gms:play-services-appset:16.0.2'
}

Dependência do Google Play Services

Se seu aplicativo não implementa o Google Play Services API 17.0.0 ou superior, adicione a dependência a seguir.

dependencies {
    implementation("com.google.android.gms:play-services-ads-identifier:17.0.0")
}

dependencies {
    implementation 'com.google.android.gms:play-services-ads-identifier:17.0.0+'
}

Método 2: instalação manual

Métodos de instalação alternativos

Download manual

Baixe e integre manualmente o arquivo AAR do SDK ao seu projeto.

Baixar o SDK: Baixe o SDK pelo link no topo desta página
Extrair e adicionar à libs: Descompacte o pacote do SDK e adicione Singular.aar ao diretório libs do seu projeto Android
Criar o diretório libs: Caso não exista, crie um diretório chamado libs na pasta do seu projeto (normalmente em <project>/app/libs )

Método 3: instalação com Maven

Instalação com Maven

Adicione o repositório Maven da Singular ao arquivo pom.xml do seu projeto.

<project ...>
    <repositories>
        <repository>
            <id>singular.net</id>
            <url>http://maven.singular.net/</url>
        </repository>
    </repositories>
</project>

Adicione a dependência:

<dependency>
    <groupId>com.singular.sdk</groupId>
    <artifactId>singular_sdk</artifactId>
    <version>12.14.0</version>
</dependency>

Método 4: instalação com Eclipse

Instalação com Eclipse

Integre o SDK usando Eclipse seguindo estas etapas.

Você pode usar o plugin Eclipse AAR: gradle-eclipse-aar-plugin

Se preferir não usar o plugin, siga estas etapas:

Descompactar o AAR: Descompacte singular_sdk-12.14.0.aar
Renomear o arquivo JAR: Renomeie classes.jar para singular_sdk-12.14.0.jar (esse é o jar principal do SDK)
Adicionar o install referrer: Adicione a biblioteca com.android.installreferrer:installreferrer:2.2 ao seu projeto
Copiar as permissões: Copie a permissão BIND_GET_INSTALL_REFERRER_SERVICE do AndroidManifest.xml contido no AAR para o seu AndroidManifest.xml
Copiar a permissão de licença: Copie a permissão CHECK_LICENSE do AndroidManifest.xml contido no AAR para o seu AndroidManifest.xml

Configuração do ProGuard

Regras do ProGuard

Adicione as regras a seguir ao seu arquivo proguard.config para evitar problemas de ofuscação de código.

-keep class com.singular.sdk.** { *; }
-keep public class com.android.installreferrer.** { *; }
# Uncomment this line in case your are calling the 'revenue' function using the Google billing library
#-keep public class com.android.billingclient.** { *; }

Permissões obrigatórias

Configuração do AndroidManifest

Adicione estas permissões dentro da tag <manifest> do seu arquivo AndroidManifest.xml .

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="BIND_GET_INSTALL_REFERRER_SERVICE" />
<uses-permission android:name="com.android.vending.CHECK_LICENSE" />
<uses-permission android:name="com.google.android.gms.permission.AD_ID" />

Exclua a permissão com.google.android.gms.permission.AD_ID se você estiver integrando o SDK para Kids .

Consultas para Samsung Galaxy Store

Para oferecer suporte ao install referrer da Samsung Galaxy Store, adicione o seguinte ao seu AndroidManifest.xml .

<queries>
    <package android:name="com.sec.android.app.samsungapps" />
</queries>

Integração do SDK

Conformidade com privacidade: Mantenha-se em conformidade com as leis de privacidade em vigor nas regiões em que você opera, incluindo GDPR, CCPA e COPPA, ao implementar os SDKs da Singular. Consulte Práticas de opt-in e opt-out do SDK para orientação.

Importar o SDK da Singular

Adicionar declaração de importação

Importe a biblioteca da Singular no seu arquivo MainActivity.

import com.singular.sdk.*

import com.singular.sdk.*;

Inicializar o SDK

Criar função de inicialização

Para habilitar o rastreamento de sessões e a atribuição, inicialize o SDK da Singular sempre que seu aplicativo for iniciado, criando um método privado e chamando-o no método onCreate() da sua MainActivity.

Siga estas etapas:

Adicionar a função: Coloque o método de inicialização dentro da classe MainActivity (ou de qualquer Activity que sirva como ponto de entrada)
Inserir as credenciais: Substitua SDK KEY e SDK SECRET pela SDK key e o SDK secret da Singular do seu dashboard
Atualizar o SingularConfig: Antes de inicializar o SDK, crie um objeto SingularConfig e defina quaisquer preferências do SDK (consulte as opções de configuração abaixo)
Chamar a função: Invoque initSingularSDK() no onCreate() após a configuração da UI, mas antes do registro de eventos

Implementação básica

Crie o método de inicialização com a configuração básica.

private fun initSingularSDK() {
    // Configure Singular with SDK key and secret
    val config = SingularConfig("SDK KEY", "SDK SECRET")

    try {
        Singular.init(applicationContext, config)
        Log.d("Singular", "SDK initialized successfully")
    } catch (e: Exception) {
        Log.e("Singular", "SDK initialization failed: ${e.message}")
    }
}

private void initSingularSDK() {
    // Configure Singular with SDK key and secret
    SingularConfig config = new SingularConfig("SDK KEY", "SDK SECRET");

    try {
        Singular.init(getApplicationContext(), config);
        Log.d("Singular", "SDK initialized successfully");
    } catch (Exception e) {
        Log.e("Singular", "SDK initialization failed: " + e.getMessage());
    }
}

Chamar a partir do onCreate da MainActivity

Invoque o método de inicialização no método onCreate() da sua MainActivity.

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)

    // Initialize Singular SDK
    initSingularSDK()

    // Proceed with your app setup (e.g., UI initialization)
}

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    // Initialize Singular SDK
    initSingularSDK();

    // Proceed with your app setup (e.g., UI initialization)
}

Diretrizes de implementação

Siga estas diretrizes principais ao implementar a inicialização do SDK.

Posicionamento: Adicione o método de inicialização na sua MainActivity, e não na classe Application, para garantir o rastreamento correto de sessões
Tratamento de erros: O bloco try-catch registra os erros de inicialização (por exemplo, credenciais inválidas) sem que o aplicativo trave
Deep linking: Para tratar deep links (URLs que abrem seu aplicativo), consulte Suporte a deep links para a configuração estendida
META Install Referrer: Adicione config.withFacebookAppId("FacebookAppID") para habilitar a atribuição via Meta Install Referrer

A partir de 18 de junho de 2025 , o Advanced Mobile Measurement Reporting (AMM) da Meta elimina a necessidade de implementar o Meta Install Referrer. Não é recomendado implementar o Meta Install Referrer se o relatório AMM estiver habilitado.

Dica profissional: Se seu aplicativo oferece suporte a vários pontos de entrada (por exemplo, deep links), garanta que initSingularSDK() seja chamado no onCreate() de cada Activity relevante para assegurar um comportamento consistente.

Opções de configuração

Métodos do SingularConfig

O objeto SingularConfig permite personalizar o comportamento do SDK usando métodos de configuração encadeáveis. Consulte a tabela abaixo para ver todas as opções disponíveis.

Método	Descrição
`.withFacebookAppId(String facebookAppID)`	Configura o Facebook App ID. Necessário para a atribuição via Meta Install Referrer . Consulte Onde posso encontrar o Facebook App ID de um aplicativo? A partir de 18 de junho de 2025 , o Advanced Mobile Measurement Reporting (AMM) da Meta elimina a necessidade de implementar o Meta Install Referrer. Não é recomendado implementar o Meta Install Referrer se o relatório AMM estiver habilitado.
`.withCustomUserId(String customId)`	Envia o ID do usuário para a Singular
`.withSingularLink(Intent intent, SingularLinkHandler handler)` `.withSingularLink(Intent intent, SingularLinkHandler handler, long shortlinkTimeoutSec)`	Habilita o deep linking com Singular Links. A sobrecarga de um argumento usa, por padrão, um tempo limite de 10 segundos para a resolução de links curtos. Para sobrescrever esse valor, use a sobrecarga de três argumentos. Esta chamada também trata os deferred deep links, de modo que não é mais necessária uma configuração separada de `withDDLHandler` / `withDDLTimeoutInSec` .
`.withOpenURI(URI openURI)`	Obtém a URI a partir do intent (para processar deep links caso o aplicativo seja aberto por um link que não tenha origem na Singular)
`.withGlobalProperty(String key, String value, boolean overrideExisting)`	Define uma propriedade global com um valor determinado. A chave e o valor serão enviados à Singular junto com qualquer evento/sessão enviado pelo aplicativo
`.withSessionTimeoutInSec(long timeout)`	Define o tempo limite da sessão
`.withFCMDeviceToken(String token)`	Define o token do FCM a ser enviado na primeira sessão
`.withLoggingEnabled()`	Habilita o registro (logging)
`.withLogLevel(int level)`	Define o nível de registro (o valor padrão é Log.ERROR)