Opciones avanzadas

Configura funciones avanzadas del SDK, incluyendo la recopilación del install referrer, la gestión de sesiones, la integración con JavaScript y los identificadores de dispositivo alternativos para casos de uso especializados.

Recopilación del install referrer (dispositivos heredados)

Descripción general

El install referrer proporciona una atribución precisa al identificar qué anuncio hizo clic el usuario antes de instalar tu aplicación desde Google Play Store.

Recopilación automática:

En dispositivos con la última versión de Google Play Store, el Singular SDK recopila el install referrer automáticamente mediante la Google Play Referrer API. Solo se necesita configuración manual para soportar dispositivos heredados.

Integrar con un receiver existente

Reenvía los datos del install referrer a Singular cuando tu aplicación ya tiene un BroadcastReceiver para INSTALL_REFERRER .

Implementación:

Agrega una llamada a SingularInstallReceiver dentro del método onReceive del 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 el receiver de Singular

Configura el receiver del install referrer de Singular cuando tu aplicación no tiene un manejador existente de INSTALL_REFERRER .

Configuración de 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>

Gestión de sesiones

Gestión automática de sesiones

El Singular SDK gestiona las sesiones automáticamente para Android API 14 (Ice Cream Sandwich) y superior, sin configuración adicional.

Comportamiento predeterminado:

Cuando la aplicación pasa a segundo plano durante 60 segundos o más, el SDK registra una nueva sesión al volver al primer plano.

Configurar el tiempo de espera de sesión

Personaliza la duración del tiempo de espera de sesión para que coincida con los patrones de uso de tu aplicación.

Firma del 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 tiempo de espera:

• Predeterminado: 60 segundos
• Mínimo: 0 segundos (cada transición entre segundo plano y primer plano crea una nueva sesión)
• Recomendado: 30 a 180 segundos según los patrones de uso de la aplicación

Gestión manual de sesiones (API < 14)

Para aplicaciones con un minSdkVersion inferior a 14, gestiona las sesiones manualmente llamando a los métodos del ciclo de vida en cada activity.

Implementación

Llama a onActivityResumed() y onActivityPaused() en los métodos del ciclo de vida de cada activity, o implementa en una clase 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
    }
}

Interfaz JavaScript para aplicaciones híbridas

Descripción general

Habilita la funcionalidad del Singular SDK desde código JavaScript en aplicaciones híbridas basadas en WebView usando SingularJSInterface .

Métodos soportados:

• setCustomUserId: Establecer un identificador de usuario personalizado
• unsetCustomUserId: Eliminar el identificador de usuario personalizado
• event: Rastrear eventos con o sin atributos
• revenue: Rastrear ingresos

Configurar la integración del WebView

Configura la interfaz JavaScript en el método onCreate() de tu activity para cada WebView que necesite funcionalidad de 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 de JavaScript

Llama a los métodos de Singular desde el código JavaScript que se ejecuta en tu 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 ingresos

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

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

Gestionar el ID de usuario personalizado

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

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

Identificadores de dispositivo alternativos

OAID (Open Advertising ID)

Habilita el tracking en dispositivos Android en regiones sin Google Play usando el Open Advertising Identifier (OAID).

Soporte de OAID:

• Dispositivos Huawei: Implementación propietaria de OAID de Huawei
• Dispositivos MSA: Marcas miembros de Mobile Security Alliance (OPPO, Vivo, Xiaomi, etc.)

Requisitos previos

Integra tanto el MSA SDK como el Huawei OAID SDK para recopilar el OAID en todas las plataformas soportadas.

Habilitar la recopilación de OAID

Configura el Singular SDK para recopilar y usar el OAID para tracking.

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)

Recopila el número IMEI del dispositivo para realizar tracking en dispositivos ubicados en regiones sin Google Play Services.

Agregar el permiso requerido

Agrega el permiso READ_PHONE_STATE a tu AndroidManifest.xml.

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

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

Obtener el número IMEI

Obtén el IMEI del dispositivo usando TelephonyManager con el manejo adecuado del nivel 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 el IMEI a Singular

Configura el IMEI durante la inicialización del SDK (recomendado) o establécelo dinámicamente después de la inicialización.

Opción 1: Método de configuración (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);

Opción 2: Método en tiempo de ejecución

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

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