Opções avançadas

Configure recursos avançados do SDK, incluindo a coleta do install referrer, gerenciamento de sessões, integração com JavaScript e identificadores de dispositivo alternativos para casos de uso especializados.

Coleta do install referrer (dispositivos legados)

Visão geral

O install referrer fornece atribuição precisa ao identificar qual anúncio o usuário clicou antes de instalar seu aplicativo na Google Play Store.

Coleta automática:

Em dispositivos com a versão mais recente da Google Play Store, o Singular SDK coleta o install referrer automaticamente usando a Google Play Referrer API. A configuração manual só é necessária para suportar dispositivos legados.

Integrar com um receiver existente

Encaminhe os dados do install referrer para o Singular quando seu aplicativo já tem um BroadcastReceiver para INSTALL_REFERRER .

Implementação:

Adicione uma chamada para SingularInstallReceiver dentro do método onReceive do receiver existente.

class MyCustomInstallReceiver : BroadcastReceiver() {
    override fun onReceive(context: Context, intent: Intent) {
        // Forward install referrer to Singular
        SingularInstallReceiver().onReceive(context, intent)

        // Your existing logic
        // ...
    }
}

public class MyCustomInstallReceiver extends BroadcastReceiver {
    @Override
    public void onReceive(Context context, Intent intent) {
        // Forward install referrer to Singular
        new SingularInstallReceiver().onReceive(context, intent);

        // Your existing logic
        // ...
    }
}

Registrar o receiver do Singular

Configure o receiver do install referrer do Singular quando seu aplicativo não tiver um handler existente de INSTALL_REFERRER .

Configuração do AndroidManifest.xml:

<application>
    <!-- Other application components -->

    <receiver
        android:name="com.singular.sdk.SingularInstallReceiver"
        android:exported="true">
        <intent-filter>
            <action android:name="com.android.vending.INSTALL_REFERRER" />
        </intent-filter>
    </receiver>
</application>

Gerenciamento de sessões

Gerenciamento automático de sessões

O Singular SDK gerencia sessões automaticamente para o Android API 14 (Ice Cream Sandwich) e versões superiores, sem configuração adicional.

Comportamento padrão:

Quando o aplicativo vai para segundo plano por 60 segundos ou mais, o SDK registra uma nova sessão ao retornar ao primeiro plano.

Configurar o tempo limite da sessão

Personalize a duração do tempo limite da sessão para corresponder aos padrões de uso do seu aplicativo.

Assinatura do método:

SingularConfig.withSessionTimeoutInSec(int timeoutInSeconds)

// Set session timeout to 120 seconds (2 minutes)
val config = SingularConfig("SDK_KEY", "SDK_SECRET")
    .withSessionTimeoutInSec(120)

Singular.init(applicationContext, config)

// Set session timeout to 120 seconds (2 minutes)
SingularConfig config = new SingularConfig("SDK_KEY", "SDK_SECRET")
    .withSessionTimeoutInSec(120);

Singular.init(getApplicationContext(), config);

Valores de tempo limite:

• Padrão: 60 segundos
• Mínimo: 0 segundos (cada transição entre segundo plano e primeiro plano cria uma nova sessão)
• Recomendado: 30 a 180 segundos, dependendo dos padrões de uso do aplicativo

Gerenciamento manual de sessões (API < 14)

Para aplicativos com minSdkVersion inferior a 14, gerencie sessões manualmente chamando métodos de ciclo de vida em cada activity.

Implementação

Chame onActivityResumed() e onActivityPaused() nos métodos de ciclo de vida de cada activity, ou implemente em uma classe base de activity.

class MainActivity : AppCompatActivity() {

    override fun onResume() {
        super.onResume()
        Singular.onActivityResumed()
        // Your other code
    }

    override fun onPause() {
        super.onPause()
        Singular.onActivityPaused()
        // Your other code
    }
}

public class MainActivity extends AppCompatActivity {

    @Override
    protected void onResume() {
        super.onResume();
        Singular.onActivityResumed();
        // Your other code
    }

    @Override
    protected void onPause() {
        super.onPause();
        Singular.onActivityPaused();
        // Your other code
    }
}

Interface JavaScript para aplicativos híbridos

Visão geral

Habilite a funcionalidade do Singular SDK a partir de código JavaScript em aplicativos híbridos baseados em WebView usando o SingularJSInterface .

Métodos suportados:

• setCustomUserId: Define um identificador de usuário personalizado
• unsetCustomUserId: Remove o identificador de usuário personalizado
• event: Rastreia eventos com ou sem atributos
• revenue: Rastreia receita

Configurar a integração do WebView

Configure a interface JavaScript no método onCreate() da sua activity para cada WebView que precisar da funcionalidade do Singular.

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

    // Initialize Singular SDK
    val config = SingularConfig("SDK_KEY", "SDK_SECRET")
    Singular.init(this, config)

    // Configure WebView
    val myWebView = findViewById<WebView>(R.id.webview)
    myWebView.settings.javaScriptEnabled = true
    myWebView.loadUrl("file:///android_asset/index.html")

    // Add Singular JavaScript interface
    val singularJSInterface = SingularJSInterface(this)
    singularJSInterface.setWebViewId(R.id.webview)
    myWebView.addJavascriptInterface(singularJSInterface, "SingularInterface")
}

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

    // Initialize Singular SDK
    SingularConfig config = new SingularConfig("SDK_KEY", "SDK_SECRET");
    Singular.init(this, config);

    // Configure WebView
    WebView myWebView = findViewById(R.id.webview);
    WebSettings webSettings = myWebView.getSettings();
    webSettings.setJavaScriptEnabled(true);
    myWebView.loadUrl("file:///android_asset/index.html");

    // Add Singular JavaScript interface
    SingularJSInterface singularJSInterface = new SingularJSInterface(this);
    singularJSInterface.setWebViewId(R.id.webview);
    myWebView.addJavascriptInterface(singularJSInterface, "SingularInterface");
}

Uso do JavaScript

Chame os métodos do Singular a partir do código JavaScript em execução no seu WebView.

Rastrear eventos

// Simple event without attributes
SingularInterface.event('level_completed');

// Event with attributes (pass as JSON string)
SingularInterface.event('purchase_attempt',
    JSON.stringify({
        "item_name": "sword",
        "item_category": "weapons",
        "item_price": 9.99
    })
);

Rastrear receita

// Track revenue in USD
SingularInterface.revenue('USD', 9.99);

// Track revenue in other currencies
SingularInterface.revenue('EUR', 8.50);

Gerenciar o ID de usuário personalizado

// Set custom user ID
SingularInterface.setCustomUserId('user_12345');

// Remove custom user ID
SingularInterface.unsetCustomUserId();

Identificadores de dispositivo alternativos

OAID (Open Advertising ID)

Habilite o rastreamento em dispositivos Android em regiões sem Google Play usando o Open Advertising Identifier (OAID).

Suporte ao OAID:

• Dispositivos Huawei: Implementação proprietária de OAID da Huawei
• Dispositivos MSA: Marcas membros da Mobile Security Alliance (OPPO, Vivo, Xiaomi etc.)

Pré-requisitos

Integre tanto o MSA SDK quanto o Huawei OAID SDK para coletar o OAID em todas as plataformas suportadas.

Habilitar a coleta do OAID

Configure o Singular SDK para coletar e usar o OAID para rastreamento.

val config = SingularConfig("SDK_KEY", "SDK_SECRET")
    .withOAIDCollection()

Singular.init(applicationContext, config)

SingularConfig config = new SingularConfig("SDK_KEY", "SDK_SECRET")
    .withOAIDCollection();

Singular.init(getApplicationContext(), config);

IMEI (International Mobile Equipment Identity)

Colete o número IMEI do dispositivo para rastreamento em dispositivos em regiões sem o Google Play Services.

Adicionar a permissão necessária

Adicione a permissão READ_PHONE_STATE ao seu AndroidManifest.xml.

<manifest>
    <uses-permission android:name="android.permission.READ_PHONE_STATE" />

    <application>
        <!-- Your application components -->
    </application>
</manifest>

Obter o número IMEI

Obtenha o IMEI do dispositivo usando o TelephonyManager com tratamento adequado do nível de API.

val telephonyManager = getSystemService(Context.TELEPHONY_SERVICE) as TelephonyManager

val imei: String? = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
    telephonyManager.imei
} else {
    @Suppress("DEPRECATION")
    telephonyManager.deviceId
}

// Validate IMEI before use
if (imei != null && imei.isNotEmpty()) {
    // Send to Singular
    Log.d("IMEI", "Retrieved: $imei")
} else {
    Log.w("IMEI", "Failed to retrieve IMEI")
}

TelephonyManager telephonyManager =
    (TelephonyManager) getSystemService(Context.TELEPHONY_SERVICE);

String imei = null;
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
    imei = telephonyManager.getImei();
} else {
    imei = telephonyManager.getDeviceId();
}

// Validate IMEI before use
if (imei != null && !imei.isEmpty()) {
    // Send to Singular
    Log.d("IMEI", "Retrieved: " + imei);
} else {
    Log.w("IMEI", "Failed to retrieve IMEI");
}

Enviar o IMEI para o Singular

Configure o IMEI durante a inicialização do SDK (recomendado) ou defina-o dinamicamente após a inicialização.

Opção 1: Método de configuração (recomendado)

// Set IMEI during initialization
val config = SingularConfig("SDK_KEY", "SDK_SECRET")
    .withIMEI(imei)

Singular.init(applicationContext, config)

// Set IMEI during initialization
SingularConfig config = new SingularConfig("SDK_KEY", "SDK_SECRET")
    .withIMEI(imei);

Singular.init(getApplicationContext(), config);

Opção 2: Método em tempo de execução

// Set IMEI after initialization
Singular.setIMEI(imei)

// Set IMEI after initialization
Singular.setIMEI(imei);