Instalación

Instalación del paquete SDK

Añade el SDK de Singular para Flutter a tu proyecto utilizando el gestor de dependencias pubspec.yaml. El SDK proporciona enlaces Dart a los SDK nativos de Singular para iOS y Android.

Añadir la dependencia del SDK

1. Actualiza pubspec.yaml: añade la dependencia del SDK de Singular para Flutter al archivo ` pubspec.yaml ` de tu proyecto:
   pubspec.yaml

   dependencies:
     flutter:
       sdk: flutter
     singular_flutter_sdk: ^1.8.0

2. Instalar dependencias: Navega hasta el directorio de tu proyecto en la terminal y ejecuta:
   bash

   flutter packages get

Configuración de la plataforma

Configuración de iOS

Completa la configuración específica de iOS para habilitar la compatibilidad del marco AdServices con el seguimiento de atribución de iOS.

Añadir el marco AdServices

El marco AdServices es necesario para la atribución de Apple Search Ads y la integración de SKAdNetwork en iOS 14.3 y versiones posteriores.

1. Accede al proyecto de iOS: abre el directorio iOS de tu proyecto de Flutter y localiza el espacio de trabajo de Xcode.
   • Ve a la carpeta « ios » de tu proyecto de Flutter.
   • Abre Runner.xcworkspace en Xcode (utiliza .xcworkspace si usas CocoaPods; de lo contrario, utiliza .xcodeproj).
2. Añade el marco AdServices: configura el marco en los ajustes de tu proyecto de Xcode.
   • En Xcode, selecciona el destino de tu proyecto (por ejemplo, «Runner»).
   • Ve a la pestaña General.
   • Desplázate hasta la sección «Frameworks, Libraries, and EmbeddedContent» .
   • Haz clic en el botón +.
   • Busca « AdServices.framework » y añádelo.
   • Establece el estado del marco en Opcional (garantiza la compatibilidad con versiones anteriores de iOS).

Configuración de Android

Configura tus archivos de compilación de Android para añadir los permisos y dependencias necesarios para que el SDK funcione correctamente.

Añadir los permisos necesarios

Añade estos permisos a tu archivo ` AndroidManifest.xml ` bajo la etiqueta ` <manifest> ` para habilitar la funcionalidad básica del SDK.

<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" />

Compatibilidad con Samsung Galaxy Store

Para habilitar el seguimiento de referencias de instalación desde Samsung Galaxy Store, añada lo siguiente a su AndroidManifest.xml:

<queries>
   <package android:name="com.sec.android.app.samsungapps" />
</queries>

Dependencias transitivas

Si ha desactivado las dependencias transitivas para el SDK de Singular en su configuración de Gradle, añada manualmente estas dependencias necesarias:

dependencies {
    // Required for install referrer tracking
    implementation 'com.android.installreferrer:installreferrer:2.2'

    // Required for App Set ID
    implementation 'com.google.android.gms:play-services-appset:16.0.0'
}

Configuración de ProGuard

Al compilar APK de lanzamiento, ProGuard (o R8) puede eliminar u ofuscar las clases del SDK . Añade estas reglas de retención para preservar la funcionalidad de Singular.

1. Localiza el archivo de ProGuard: ve a android/app/proguard-rules.pro en tu proyecto de Flutter.
2. Añade reglas de retención: añade las siguientes reglas para conservar las clases del SDK:
   android/app/proguard-rules.pro

   # Preserve Singular SDK classes
   -keep class com.singular.sdk.** { *; }
   
   # Preserve Android Install Referrer library
   -keep public class com.android.installreferrer.** { *; }
   
   # Uncomment if using Singular revenue tracking with Google Play Billing Library
   #-keep public class com.android.billingclient.** { *; }

Integración del SDK

Inicialice el SDK de Singular cada vez que se inicie su aplicación. La inicialización del SDK es esencial para todas las funciones de atribución de Singular y crea una nueva sesión para calcular las métricas de retención de usuarios.

Importar clases del SDK

Importe las clases del SDK de Singular al principio del archivo principal de su aplicación (normalmente main.dart).

import 'package:singular_flutter_sdk/singular.dart';
import 'package:singular_flutter_sdk/singular_config.dart';

Acerca del SDID

El Singular Device ID (SDID) es un identificador a nivel de dispositivo que Singular genera y administra. En una integración híbrida, donde este SDK se ejecuta en tu app y tu servidor también envía eventos a través de la API Server-to-Server (S2S), enviar el mismo SDID en esos eventos del lado del servidor los vincula al mismo dispositivo que el SDK está rastreando. Esto permite que Singular atribuya la actividad del SDK y de S2S a un único dispositivo sin depender de identificadores publicitarios específicos de la plataforma.

Inicialice el SDK

Cree un objeto ` SingularConfig ` con sus credenciales del SDK, configure las funciones opcionales e inicialice el SDK utilizando el método ` start() `.

Inicialización básica

1. Obtener credenciales: Inicie sesión en su cuenta de Singular y vaya a Herramientas para desarrolladores > Integración del SDK > Claves del SDK para encontrar su clave y secreto del SDK.
2. Crear configuración: instancie un objeto SingularConfig con sus credenciales.
3. Añadir configuración: Opcionalmente, configura el comportamiento del SDK utilizando los setters de propiedades (consulta Referencia de configuración).
4. Inicializar el SDK: Llama a Singular.start() para iniciar el SDK.

Ejemplo de inicialización

Inicialice el SDK en el punto de entrada de su aplicación, normalmente dentro del método initState() de su StatefulWidget principal.

import 'package:flutter/material.dart';
import 'package:singular_flutter_sdk/singular.dart';
import 'package:singular_flutter_sdk/singular_config.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatefulWidget {
  @override
  _MyAppState createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  @override
  void initState() {
    super.initState();

    // Create configuration with credentials
    SingularConfig config = SingularConfig(
      'YOUR_SDK_KEY',
      'YOUR_SDK_SECRET'
    );

    // Log the SDID once the SDK receives it (SDID is enabled by default for new accounts)
    config.sdidReceivedCallback = (String sdid) {
      print('Singular SDID received: $sdid');
    };

    // Enable debug logging
    config.enableLogging = true;
    config.logLevel = 4;

    // Set session timeout (in seconds)
    config.sessionTimeout = 60.0;

    // Initialize SDK
    Singular.start(config);
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      home: MyHomePage(),
    );
  }
}

Ejemplo de configuración avanzada

Configure múltiples funciones del SDK durante la inicialización estableciendo propiedades adicionales en el objeto SingularConfig antes de llamar a start() .

import 'package:flutter/material.dart';
import 'package:singular_flutter_sdk/singular.dart';
import 'package:singular_flutter_sdk/singular_config.dart';
import 'package:singular_flutter_sdk/singular_link_params.dart';
import 'package:singular_flutter_sdk/singular_global_property.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatefulWidget {
  @override
  _MyAppState createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  @override
  void initState() {
    super.initState();
    initializeSingularSDK();
  }

  void initializeSingularSDK() {
    // Create configuration with credentials
    SingularConfig config = SingularConfig(
      'YOUR_SDK_KEY',
      'YOUR_SDK_SECRET'
    );

    // User identification
    config.customUserId = 'user_123456';

    // Privacy settings
    config.limitDataSharing = false;
    
    // Deep linking handler
    config.singularLinksHandler = (SingularLinkParams params) {
      print('Deep link received: ${params.deeplink}');
      print('Passthrough params: ${params.passthrough}');
      print('Is deferred: ${params.isDeferred}');
      // Handle navigation based on deep link
    };

    // Short link timeout
    config.shortLinkResolveTimeOut = 10.0;

    // Facebook integration
    config.facebookAppId = 'YOUR_FACEBOOK_APP_ID';

    // SKAdNetwork settings (iOS)
    config.skAdNetworkEnabled = true;
    config.manualSkanConversionManagement = false;
    config.waitForTrackingAuthorizationWithTimeoutInterval = 30;

    // Conversion value callbacks (iOS)
    config.conversionValueUpdatedCallback = (int conversionValue) {
      print('Conversion value updated: $conversionValue');
    };

    config.conversionValuesUpdatedCallback = (int cv, int coarse, bool lock) {
      print('Fine: $cv, Coarse: $coarse, Locked: $lock');
    };

    // Global properties
    config.globalProperties = [
      SingularGlobalProperty('app_version', '2.5.0', true),
      SingularGlobalProperty('user_tier', 'premium', false)
    ];

    // Debugging
    config.enableLogging = true;
    config.logLevel = 4;

    // Session timeout
    config.sessionTimeout = 60.0;

    // Initialize SDK
    Singular.start(config);
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      home: MyHomePage(),
    );
  }
}

Configuración avanzada

Requisitos para la medición de conversiones integrada de Google Ads en iOS

Si su aplicación ejecuta campañas de Google Ads dirigidas a usuarios de iOS 14.5 o superior, se requieren pasos de configuración adicionales del SDK para admitir la medición de conversiones integrada (ICM) de iOS. Esto incluye:

• Integrar el SDK de medición en el dispositivo (ODM) de Google
• Actualización al SDK de Singular para iOS v12.8.1+ (o v5.5.0+ para Unity, v1.8.0+ para Flutter/Cordova, v3.9.0+ para React Native)
• Añadir el indicador del enlazador « -ObjC » y habilitar « enableOdmWithTimeoutInterval » en SingularConfig

Nota: Al habilitar enableOdmWithTimeoutInterval se retrasa la inicialización del SDK y puede aplazarse la recepción de callbacks de enlaces profundos. Realice esta configuración durante la implementación inicial del SDK para evitar tener que volver a trabajar en ello.

Consulte los requisitos técnicos completos de ICM para iOS