Baixar SDK do Android versão 12.13.0

Guia em vídeo disponível

Assista a este vídeo para um passo a passo detalhado do processo de integração. Use o vídeo e o guia escrito abaixo em conjunto para obter os melhores resultados.

Pré-requisitos

Conclua os passos em Integração de um SDK da Singular: planejamento e pré-requisitos antes de prosseguir com esta integração.

Importante: Estes passos de pré-requisitos são obrigatórios para qualquer integração do SDK da Singular.

Instalação

Métodos de instalação

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

Método 1: Gradle (recomendado)

Adicionar o 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 o uso de declarações de repositório centralizadas em settings.gradle ou settings.gradle.kts em vez de declarações no nível do projeto ou módulo em build.gradle .

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 no nível do 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 app.

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

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

Resolução de problemas: classes duplicadas

Você pode encontrar erros de classes duplicadas quando várias dependências incluem a mesma biblioteca. Isso ocorre comumente com 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 dependências em conflito

Para resolver problemas de classes duplicadas, exclua a dependência transitiva (transitive dependency) em conflito do SDK da Singular ou de outras dependências que estejam causando o conflito.

dependencies {
    // Exclude specific Google Play Services modules from Singular SDK
    implementation("com.singular.sdk:singular_sdk:12.13.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.13.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 de exclusão globais

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

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

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

Verificar a 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 app, mostrando quais bibliotecas estão incluídas e quais foram excluídas.

Suporte para Samsung Galaxy Store

Adicione a dependência do install referrer da Samsung Galaxy Store se o seu app 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 (Transitive Dependencies)

Se você desativou as dependências transitivas do SDK da Singular, adicione manualmente estas bibliotecas necessárias às dependências do módulo do seu app.

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 o seu app não implementa o Google Play Services API 17.0.0 ou superior, adicione a seguinte dependência.

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 no seu projeto.

Baixar o SDK: Baixe o SDK pelo link no topo desta página
Extrair e adicionar a libs: Descompacte o pacote do SDK e adicione Singular.aar ao diretório libs do seu projeto Android
Criar o diretório libs: Se ele não existir, crie um diretório chamado libs na pasta do seu projeto (geralmente 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.13.0</version>
</dependency>

Método 4: instalação com Eclipse

Instalação com Eclipse

Integre o SDK usando o Eclipse seguindo estes passos.

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

Se não quiser utilizar o plugin, siga estes passos:

Descompactar o AAR: Descompacte singular_sdk-12.13.0.aar
Renomear o arquivo JAR: Renomeie classes.jar para singular_sdk-12.13.0.jar (este é 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 seguintes regras 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 abaixo da tag <manifest> no 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 estiver integrando o Kids SDK .

Consultas para Samsung Galaxy Store

Para dar 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 de privacidade: Cumpra as leis de privacidade em vigor nas regiões em que você atua, incluindo GDPR, CCPA e COPPA, ao implementar os SDKs da Singular. Veja Práticas de opt-in e opt-out do SDK para orientação.

Importar o SDK da Singular

Adicionar a instrução de Import

Importe a biblioteca da Singular no seu arquivo MainActivity.

import com.singular.sdk.*

import com.singular.sdk.*;

Inicializar o SDK

Criar a função de inicialização

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

Siga estes passos:

Adicionar a função: Coloque o método de inicialização dentro da sua classe MainActivity (ou de qualquer Activity de ponto de entrada)
Inserir as credenciais: Substitua SDK KEY e SDK SECRET pela SDK key e pelo secret da Singular do seu dashboard
Atualizar o SingularConfig: Antes de inicializar o SDK, crie um objeto SingularConfig e defina as 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 de registrar 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 à sua MainActivity, e não à 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 travar o seu app
Deep linking: Para tratar deep links (URLs que abrem o seu app), consulte Suporte a deep links para a configuração estendida
META Install Referrer: Adicione config.withFacebookAppId("FacebookAppID") para habilitar a atribuição de 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 caso os relatórios do AMM estejam habilitados.

Pro Tip: Se o seu app suporta vários pontos de entrada (por exemplo, deep links), garanta que initSingularSDK() seja chamado no onCreate() de cada Activity relevante para garantir 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 todas as opções disponíveis.

Método	Descrição
`.withFacebookAppId(String facebookAppID)`	Configura o Facebook App ID. Obrigatório para a atribuição de Meta Install Referrer . Veja Onde posso encontrar o Facebook App ID de um app? 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 caso os relatórios do AMM estejam habilitados.
`.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 deep linking com Singular Links. A sobrecarga de um argumento usa, por padrão, um timeout de resolução de short link de 10 segundos; utilize a sobrecarga de três argumentos para sobrescrevê-lo. Essa chamada também trata os deferred deep links, portanto uma configuração separada de `withDDLHandler` / `withDDLTimeoutInSec` não é mais necessária.
`.withOpenURI(URI openURI)`	Obtém o URI a partir do intent (para processar deep links se o app for 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 key e o value serão enviados para a Singular junto com qualquer evento/sessão enviado pelo app
`.withSessionTimeoutInSec(long timeout)`	Define o timeout da sessão
`.withFCMDeviceToken(String token)`	Define o token do FCM a ser enviado na primeira sessão
`.withLoggingEnabled()`	Habilita o logging
`.withLogLevel(int level)`	Configura o nível de logging (o padrão é Log.ERROR)