Documento

Descarregar a versão 12.10.0 do SDK do Android

Informações sobre o SDK de aplicações para crianças

Exemplo de aplicação (Java)
Reveja uma integração completa

Guia em vídeo disponível

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

Pré-requisitos

Conclua as etapas em Integração de um SDK Singular: Planejamento e pré-requisitos antes de prosseguir com essa integração.

Importante: essas etapas de pré-requisito são necessárias para qualquer integração do Singular SDK.

Instalação

Métodos de instalação

Observação: O Android Studio agora usa como padrão 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 SDK

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

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

Configuração do Gradle 7+

Adicione o repositório Singular SDK ao seu arquivo de configurações:

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 seu arquivo de compilação no nível do projeto:

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

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

Adicionar dependência da biblioteca Singular

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

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

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

Solução de problemas: Problemas de classe duplicada

Você pode encontrar erros de classe duplicada quando várias dependências incluem a mesma biblioteca. Isso geralmente ocorre 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

Resolução: Excluir dependências conflitantes

Para resolver problemas de classe duplicada, exclua a dependência transitiva conflitante do SDK 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.10.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.10.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 classe duplicada afetar várias dependências em seu projeto, é possível 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'
}

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

Depois de aplicar as regras de exclusão, verifique a árvore de dependências para garantir que os conflitos sejam resolvidos.

./gradlew app:dependencies --configuration debugRuntimeClasspath

Este comando apresenta a árvore de dependências completa da sua aplicação, mostrando quais as bibliotecas que estão incluídas e quais as que foram excluídas.

Suporte da Samsung Galaxy Store

Adicione a dependência do referenciador de instalação da Samsung Galaxy Store se a sua aplicação for distribuída através da 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 Singular, adicione manualmente essas bibliotecas necessárias às dependências do módulo do seu aplicativo.

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

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

Dependência do Google Play Services

Se o seu aplicativo não implementar a API 17.0.0 ou superior do Google Play Services, 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 SDK AAR ao seu projeto.

Faça o download do SDK: Faça o download do SDK a partir do link no topo desta página
Extrair e adicionar às bibliotecas: Descompacte o pacote SDK e adicione Singular.aar ao diretório libs do seu projeto Android
Criar diretório libs: Se não existir, crie um diretório chamado libs na pasta do seu projeto (normalmente em <project>/app/libs)

Método 3: Instalação do Maven

Instalação do Maven

Adicione o repositório Singular Maven ao ficheiro pom.xmldo 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.10.0</version>
</dependency>

Método 4: Instalação do Eclipse

Instalação do Eclipse

Integre o SDK usando o Eclipse seguindo estas etapas.

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

Se não quiser usar o plug-in, siga estas etapas:

Descompacte o AAR: Descompactar singular_sdk-12.10.0.aar
Renomear o arquivo JAR: Renomear classes.jarpara singular_sdk-12.10.0.jar (este é o jar principal do SDK)
Adicionar referenciador de instalação: Adicionar a biblioteca com.android.installreferrer:installreferrer:2.2ao seu projeto
Copiar permissões: Copie a permissão BIND_GET_INSTALL_REFERRER_SERVICE do AndroidManifest.xml contido no AAR para o seu AndroidManifest.xml
Copiar 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 ficheiro 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 necessárias

Configuração do AndroidManifest

Adicione estas permissões sob a etiqueta <manifest> no seu ficheiro 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 a integrar o Kids SDK.

Consultas da Samsung Galaxy Store

Para suportar o referenciador de instalação 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 a privacidade: Mantenha-se em conformidade com as leis de privacidade promulgadas nas regiões onde faz negócios, incluindo GDPR, CCPA e COPPA, ao implementar os SDKs Singular. Consulte Práticas de Opt-In e Opt-Out do SDKpara obter orientação.

Importar Singular SDK

Adicionar declaração de importação

Importe a biblioteca 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 e a atribuição de sessões, inicialize o SDK Singular sempre que seu aplicativo for iniciado, criando um método privado e chamando-o a partir do método onCreate() de sua MainActivity.

Siga estas etapas:

Adicione a função: Coloque o método de inicialização dentro da sua classe MainActivity (ou qualquer Activity de ponto de entrada)
Insira as credenciais: Substitua SDK KEYe SDK SECRET pela sua chave e segredo do Singular SDK do seu painel de controlo
Atualizar SingularConfig: Antes de inicializar o SDK, crie um objeto SingularConfig e defina quaisquer preferências do SDK (consulte Opções de configuração abaixo)
Chamar a função: Invoque initSingularSDK() em onCreate() após a configuração da interface do usuário, 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());
    }
}

Chamada de MainActivity onCreate

Chame 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.

Colocação: Adicione o método de inicialização em seu MainActivity, não na classe Application, para garantir o rastreamento adequado da sessão
Tratamento de erros: O bloco try-catch regista os erros de inicialização (por exemplo, credenciais inválidas) sem bloquear a aplicação
Deep Linking: Para lidar com links profundos (URLs que iniciam seu aplicativo), consulte Suporte a links profundospara configuração estendida
META Install Referrer: Adicione config.withFacebookAppId("FacebookAppID") para ativar a atribuição do 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 ativado.

Dica profissional: Se a sua aplicação suportar vários pontos de entrada (por exemplo, deep links), certifique-se de que initSingularSDK() é chamado em cada atividade relevante onCreate() para garantir um comportamento consistente.

Opções de configuração

Métodos 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)`	Configurar a ID do aplicativo do Facebook. Necessário para a atribuição do Referenciador de instalação do Meta. Consulte Onde posso encontrar o ID do aplicativo do Facebook de um aplicativo? A partir de 18 de junho de 2025, o Relatório de medição móvel avançada (AMM)do Meta elimina a necessidade de implementar o Referenciador de instalação do Meta. Não é recomendado implementar o Referenciador de instalação do Meta se o relatório AMM estiver ativado.
`.withCustomUserId(String customId)`	Enviar o ID do utilizador para o Singular
`.withSingularLink(getIntent(), SingularLinkHandler handler)`	Habilitar o deep linking com Singular Links
`.withDDLTimeoutInSec(long timeout)`	Defina o período de tempo que o Singular procura por um link direto diferido quando o aplicativo é aberto pela primeira vez
`.withOpenURI(URI openURI)`	Buscar o URI da intenção (para processar links diretos se o aplicativo for aberto por meio de um link que não seja originário do Singular)
`.withGlobalProperty(String key, String value, boolean overrideExisting)`	Definir uma propriedade global para um determinado valor. A chave e o valor serão enviados para o Singular com qualquer evento/sessão enviado pelo aplicativo
`.withSessionTimeoutInSec(long timeout)`	Definir o tempo limite da sessão
`.withFCMDeviceToken(String token)`	Define o token FCM a ser enviado na primeira sessão
`.withLoggingEnabled()`	Ativar o registo
`.withLogLevel(int level)`	Configurar o nível de registo (o padrão é Log.ERROR)