Opções avançadas

Configure funcionalidades avançadas do SDK, incluindo instalar a coleção de referenciadores, gestão de sessões, integração de JavaScript e identificadores de dispositivos alternativos para casos de utilização especializados.

Instalar coleção de referenciadores (dispositivos antigos)

Visão geral

O referenciador de instalação fornece uma atribuição precisa ao identificar em que anúncio o utilizador clicou antes de instalar a sua aplicação a partir da Google Play Store.

Recolha automática:

Em dispositivos com a última versão da Google Play Store, o Singular SDK coleta o referenciador de instalação automaticamente usando a API Google Play Referrer. A configuração manual é necessária apenas para suporte a dispositivos antigos.

Integrar com o recetor existente

Encaminhe os dados do referenciador de instalação para a Singular quando seu aplicativo já tiver um BroadcastReceiver para INSTALL_REFERRER.

Implementação:

Adicione uma chamada para SingularInstallReceiver dentro do método onReceive do seu recetor 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 recetor Singular

Configure o recetor do referenciador de instalação Singular quando seu aplicativo não tiver um manipulador INSTALL_REFERRER existente.

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>

Gestão de sessões

Gerenciamento automático de sessão

O Singular SDK lida automaticamente com o gerenciamento de sessão para Android API 14 (Ice Cream Sandwich) e superior sem configuração adicional.

Comportamento padrão:

Quando a aplicação passa para segundo plano durante 60 segundos ou mais, o SDK regista uma nova sessão ao regressar 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 utilização da sua aplicação.

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 de plano de fundo/primeiro plano cria uma nova sessão)
• Recomendado: 30-180 segundos, dependendo dos padrões de uso do aplicativo

Gerenciamento manual de sessões (API < 14)

Para aplicativos com minSdkVersion abaixo de 14, gerencie manualmente as sessões chamando métodos de ciclo de vida em cada atividade.

Implementação

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

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 aplicações híbridas

Visão geral

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

Métodos suportados:

• setCustomUserId: Definir o identificador de utilizador personalizado
• unsetCustomUserId: Remover o identificador de utilizador personalizado
• event (evento): Rastrear eventos com ou sem atributos
• revenue (receita): Acompanhar a receita

Configurar a integração do WebView

Configure a interface JavaScript no método onCreate() da sua atividade para cada WebView que precisa da funcionalidade 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 Singular a partir do código JavaScript em execução no seu WebView.

Acompanhar 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
    })
);

Acompanhar receitas

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

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

Gerir ID de utilizador personalizado

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

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

Identificadores de dispositivos alternativos

OAID (Open Advertising ID)

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

Suporte OAID:

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

Pré-requisitos

Integrar o SDK MSAe o SDK OAID da Huaweipara recolher OAID em todas as plataformas suportadas.

Ativar a recolha de OAID

Configure o SDK Singular 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 (Identidade Internacional de Equipamento Móvel)

Recolha o número IMEI do dispositivo para rastreio de dispositivos em regiões sem o Google Play Services.

Adicionar 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>

Recuperar o número IMEI

Obtenha o IMEI do dispositivo utilizando o TelephonyManager com o tratamento adequado ao nível da 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 IMEI para a 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 de tempo de execução

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

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