Antes de empezar: Requisitos previos del SDK

Siga los pasos indicados en Integración de un SDK Singular: Planificación y requisitos previos.

Estos pasos son requisitos previos para cualquier integración de Singular SDK.

1. Instalación del SDK

Puede instalar Singular SDK utilizando CocoaPods, el gestor de paquetes Swift o una biblioteca estática.

2. Configuración de una integración SDK básica

2.1. Importación de la librería Singular

En el SceneDelegate, AppDelegate, o cualquier archivo donde se utilizará Singular, importar la biblioteca de clases Singular para empezar a utilizar el SDK Singular.

// Si se instala con Cocoapods o Swift Package Manager
import Singular

// Si se instala manualmente en Objective-C (Nuevo marco)
#import <Singular/Singular.h>

// Si se instala manualmente en Objective-C (Legado)
#import "Singular.h"

2.2. Creación de un objeto de configuración

Antes de inicializar la funcionalidad de Singular en su código, debe crear un objeto de configuración de Singular y establecer todas sus opciones de configuración. Este bloque de código debe añadirse en SceneDelegate (o si no utiliza SceneDelegate, añádalo a AppDelegate).

El siguiente ejemplo de código crea un objeto de configuración y establece algunas opciones de configuración comunes, como activar SKAdNetwork en modo gestionado y establecer un tiempo de espera para una respuesta ATT.

En las secciones siguientes se ofrecen más detalles sobre cada una de estas opciones y sobre cómo personalizarlas.

Ejemplo: Creación de un objeto de configuración con algunas opciones comunes

func getConfig() -> SingularConfig? {
          // Cree el objeto de configuración con la clave SDK y el secreto SDK
          guard let config = SingularConfig(apiKey: Constants.APIKEY, andSecret:
          Constants.SECRET) else {
              return nil
          }
              
          /* Establezca un retraso de 300 segundos antes de la inicialización para esperar la respuesta ATT del usuario. ¡Elimine esto si no muestra un mensaje ATT!*/
          config.waitForTrackingAuthorizationWithTimeoutInterval = 300
              
          // Admite dominios ESP personalizados
          config.espDomains = ["links.your-website-domain.com"]
              
          // Establecer un método de controlador para enlaces profundos
          config.singularLinksHandler = { params in
              self.handleDeeplink(params: params)
          }
              
          return config
      }

- (SingularConfig *)getConfig {
          // Cree el objeto de configuración con la clave SDK y el secreto SDK
          SingularConfig* config = [[SingularConfig alloc] initWithApiKey:APIKEY andSecret:SECRET];
      
          /* Establezca un retraso de 300 segundos antes de la inicialización para esperar la respuesta ATT del usuario. ¡Elimine esto si no muestra un mensaje ATT!*/
          config.waitForTrackingAuthorizationWithTimeoutInterval = 300;
      
          // Admite dominios ESP personalizados
          config.espDomains = @[@"links.your-website-domain.com"];
      
          // Establecer un método de controlador para enlaces profundos
          config.singularLinksHandler = ^(SingularLinkParams * params) {[self handleDeeplink:params];};
          
          return config;
      }

// Habilite SKAdNetwork en modo administrado
config.skAdNetworkEnabled = true

// Habilite SKAdNetwork en modo administrado
config.skAdNetworkEnabled = YES;

2.3. Personalización de las opciones de SKAdNetwork

SKAdNetwork es el marco de trabajo de Apple para determinar la atribución de instalaciones móviles sin comprometer la privacidad del usuario final. SKAdNetwork le permite medir el rendimiento de sus campañas de marketing de aplicaciones sin compartir la información de identificación personal del usuario.

Por defecto, SKAdNetwork está habilitado en Modo Gestionado, donde el valor de conversión es gestionado directamente por Singular desde el lado del servidor. Si utiliza el modo gestionado, no necesita añadir ningún código a su aplicación para gestionar SKAdNetwork.

Esto permite la máxima flexibilidad, ya que puede establecer y cambiar sus valores de conversión a través de la plataformaSingular sin modificar su código del lado del cliente.

Este modo gestionado del lado del servidor también le ayuda a manejar los temporizadores de SKAdNetwork. SKAdNetwork le permite actualizar el valor de conversión en un plazo de 24 horas desde el momento del registro en SKAdNetwork. Cualquier llamada para actualizar el valor de conversión prolonga el temporizador 24 horas más. Por lo tanto, al elegir sus eventos de conversión, tendrá que asegurarse de que los eventos se produzcan dentro de esa ventana de actualización. En el modo gestionado, puede cambiar la configuración de los eventos de conversión en cualquier momento sin necesidad de lanzar una nueva versión de su aplicación.

Uso de SKAdNetwork en modo manual (Avanzado)

func getConfig() -> SingularConfig? {
          // Opciones de configuración singulares
          guard let config = SingularConfig(apiKey: Constants.APIKEY,
                  andSecret: Constants.SECRET) else {
              return nil
          }
          ...
          config.manualSkanConversionManagement = true
          ...
          return config
      }

- (SingularConfig *)getConfig {
          // Opciones de configuración singulares
          SingularConfig* config = [[SingularConfig alloc] initWithApiKey:APIKEY
              andSecret:SECRET];
          ...
          config.manualSkanConversionManagement = YES;
          ...
          return config;
      }

// Envío de un evento estándar para iniciar sesión
Singular.event(EVENT_SNG_LOGIN)
      
// Actualizar manualmente el valor de conversión a 7 después del evento
Singular.skanUpdateConversionValue(7)

// Envío de un evento estándar para iniciar sesión
[Singular event:EVENT_SNG_LOGIN];
      
// Actualizar manualmente el valor de conversión a 7 después del evento
[Singular skanUpdateConversionValue:7];

let conversionValue = Singular.skanGetConversionValue()

NSNumber* conversionValue = [Singular skanGetConversionValue]; 

func getConfig() -> SingularConfig? {
          // Opciones de configuración singulares
          guard let config = SingularConfig(apiKey: Constants.APIKEY,
              andSecret: Constants.SECRET)
          else {         
              return nil     
          }     
          ...     
          config.conversionValueUpdatedCallback = { conversionValue in
              // Aquí tienes acceso al último valor de conversión.
          }
          ...
          return config
      } 

- (SingularConfig *)getConfig {
  // Opciones de configuración singulares
  SingularConfig* config = [[SingularConfig alloc] initWithApiKey:APIKEY
    andSecret:SECRET];
  ...
  config.conversionValueUpdatedCallback=^(NSNumber *conversionValue, 
    NSNumber *coarse, BOOL lock) {
    // Aquí tienes acceso al último valor de conversión.
  };
  ...
  return config;
}

2.4. Manejo del Consentimiento ATT (Estableciendo un Retraso de Inicialización)

Visualización de un aviso ATT (App Tracking Transparency)

A partir de iOS 14.5, las aplicaciones están obligadas a pedir el consentimiento del usuario (utilizando el marco App Tracking Transparency) antes de que puedan acceder y compartir algunos datos de usuario que son útiles para fines de seguimiento, incluyendo el IDFA del dispositivo.

Singular se beneficia enormemente de tener el IDFA para identificar dispositivos y realizar la atribución de instalaciones (aunque hay formas de realizar la atribución sin el IDFA). Recomendamos encarecidamente que pidas el consentimiento del usuario para obtener el IDFA.

Retrasar la inicialización para esperar la respuesta de la ATT

Por defecto, Singular SDK envía una sesión de usuario cuando se inicializa. Cuando se envía una sesión desde un nuevo dispositivo, se activa inmediatamente el proceso de atribución de Singular, que se realiza basándose únicamente en los datos de que dispone Singular en ese momento. Por lo tanto, es esencial solicitar el consentimiento yrecuperar el IDFA antes de que Singular SDK envíe la primera sesión.

Para retrasar el disparo de una sesión de usuario, inicialice Singular SDK con la opción waitForTrackingAuthorizationWithTimeoutInterval en el objeto Config. Esta opción ya está incluida en el ejemplo de código en 2.2. Creación de un objeto Config.

func getConfig() -> SingularConfig? {
          guard let config = SingularConfig(apiKey: Constants.APIKEY,
              andSecret: Constants.SECRET) else {
              return nil
          }
          ...
          config.waitForTrackingAuthorizationWithTimeoutInterval = 300
          ...
          return config
      }

- (SingularConfig *)getConfig {
          SingularConfig* config = [[SingularConfig alloc] initWithApiKey:APIKEY
              andSecret:SECRET];
          ...
          config.waitForTrackingAuthorizationWithTimeoutInterval = 300;
          ...
          return config;
      }

2.5. Gestión de enlaces profundos

Cuando un usuario hace clic en un enlace profundo en un dispositivo que tiene instalada la aplicación, ésta se abre y muestra un producto o experiencia específicos.

Los enlaces de seguimiento de Singular pueden incluir la funcionalidad de enlaces profundos, así como la de enlaces profundos diferidos(consulte nuestras Preguntas frecuentes sobre enlaces profundos y las Preguntas frecuentes sobre enlaces singulares para obtener más información).

El Singular SDK Config, implementado en el paso anterior, hace referencia a una función de devolución de llamada ("handleDeeplink"). La función "handleDeeplink" es necesaria para activar la compatibilidad con enlaces profundos y enlaces profundos diferidos a través de Singular SDK.

Requisitos previos para implementar enlaces profundos

Asegúrese de haber completado los siguientes pasos:

• Siga las instrucciones de Singular Links Prerequisites.
• En Xcode, añada un subdominio personalizado de Singular a Signing & Capabilities > Associated Domains.
• Añada el esquema de la aplicación a sus Tipos de URL en Información > Tipos de URL.
• Añada su ID de equipo de desarrollador de Apple y su esquema en la página Apps de la plataforma Singular.

Creación del método de devolución de llamada para el controlador

El siguiente ejemplo de código crea un método de devolución de llamada denominado handleDeeplink (a este método se hace referencia en el ejemplo de código Config anterior).

La firma del bloque es void(^)(SingularLinkParams*). El SingularLinkParams contiene el destino del deep link, los parámetros passthrough, y si el enlace es diferido o no.

func handleDeeplink(params: SingularLinkParams?) {
          // Obtenga datos de Deeplink de Singular Link
          let deeplink = params?.getDeepLink()
          let passthrough = params?.getPassthrough()
          let isDeferredDeeplink = params?.isDeferred()
          let urlParams = params?.getURLParameters()
          // Agregue el código de manejo de enlaces profundos aquí
      }

- (void)handleDeeplink:(SingularLinkParams*)params{
          // Obtenga datos de Deeplink de Singular Link
          NSString* deeplink = [params getDeepLink];
          NSString* passthrough = [params getPassthrough];
          BOOL isDeferredDeeplink = [params isDeferred];
          NSDictionary *urlParams = [params getURLParameters];
          // Agregue el código de manejo de enlaces profundos aquí
      }

Otras Opciones de Enlace

func getConfig() -> SingularConfig? {
          // Opciones de configuración singulares
          guard let config = SingularConfig(apiKey: Constants.APIKEY,
              andSecret: Constants.SECRET) else {
              return nil
          }
          ...
          config.supportedDomains = ["subdomain.mywebsite.com","anothersubdomain.myotherwebsite.com"]
          ...
          return config
      }

- (SingularConfig *)getConfig {
          // Opciones de configuración singulares
          SingularConfig* config = [[SingularConfig alloc] initWithApiKey:APIKEY
              andSecret:SECRET];
          ...
          config.supportedDomains = @[@"subdomain.mywebsite.com","anothersubdomain.myotherwebsite.com"];
          ...
          return config;
      }

func getConfig() -> SingularConfig? { 
          // Opciones de configuración singulares 
          guard let config = SingularConfig(apiKey: Constants.APIKEY,
              andSecret: Constants.SECRET) else { 
              return nil 
          } 
          ... 
          config.espDomains = ["links.mywebsite.com"] 
          ... 
          return config 
      } 

- (SingularConfig *)getConfig { 
          // Opciones de configuración singulares 
          SingularConfig* config = [[SingularConfig alloc] initWithApiKey:APIKEY
              andSecret:SECRET]; 
          ... 
          config.espDomains = @[@"links.mywebsite.com"]; 
          ... 
          return config; 
      } 

2.6. Inicialización de Singular

El SDK de Singular debe inicializarse cada vez que se abre la aplicación. Es un requisito previo para todas las funciones de atribución de Singular y también envía una nueva sesión de usuario a Singular (las sesiones se utilizan para calcular la retención de usuarios). El SDK se inicializa utilizando el objeto de configuración que creó en 2.2. Creación de un objeto de configuración. Creación de un objeto config.

¿Dónde añadir el código de inicialización?

Tiene que inicializar el SDK Singular en cada punto de entrada a la aplicación:

• Para iOS 13+ utilizando la interfaz SwiftUI sin SceneDelegate o AppDelegate, inicialice el Singular SDK en los siguientes ContentView().onOpenURL() y .onChange(of: scenePhase) (Vea el código de abajo como ejemplo).

• Para iOS 13+, inicialice Singular SDK en las siguientes funciones de SceneDelegate: willConnectTo session, continue userActivity, openURLContexts URLContexts.

• Para versiones anteriores de iOS que no admitan SceneDelegate, inicialice el SDK en las siguientes funciones de AppDelegate: didFinishLaunchingWithOptions, continueUserActivity, openURL.

Ejemplos de código de inicialización

// INICIALIZAR EL SDK EN LAS SIGUIENTES FUNCIONES SCENEDELEGATE
     
// willConnectTo session
func scene(_ scene: UIScene, willConnectTo session: UISceneSession,
  options connectionOptions: UIScene.ConnectionOptions) {
    let userActivity = connectionOptions.userActivities.first
    // Imprimir IDFV en la consola para utilizarlo en la consola de Singular SDK
    print(Date(), "-- Scene Delegate IDFV:", 
    UIDevice().identifierForVendor!.uuidString as Any)
    
    // Inicialice el SDK Singular aquí:
    if let config = self.getConfig() {
      config.userActivity = userActivity
      Singular.start(config)
    }
}
      
// continue userActivity
      
func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
  // Inicia una nueva sesión Singular en continueUserActivity
  if let config = self.getConfig() {
    config.userActivity = userActivity
    Singular.start(config)
  }
}
      
//openURLContexts URLContexts
      
func scene(_ scene: UIScene, openURLContexts URLContexts: 
  Set<UIOpenURLContext>) {
    // Inicia una nueva sesión Singular al arrancar en frío desde el esquema deeplink
    if let config = self.getConfig() {
      config.openUrl = openurlString
      Singular.start(config)
    }
    
    // Añadir código personalizado aquí para redirigir a enlaces profundos no Singular
    //...
}

// INICIALIZAR EL SDK EN LAS SIGUIENTES FUNCIONES WINDOWGROUP
var body: some Scene {
    WindowGroup {
        ContentView()
            .onOpenURL(perform: { url in
                openURL = url
                // Inicializar Singular desde una openURL
                if let config = self.getConfig() {
                    config.openUrl = url
                    Singular.start(config)
                }
            })
    }
    .onChange(of: scenePhase) { oldValue, phase in
        // El SwiftUI ScenePhases sustituye a los antiguos eventos del ciclo de vida SceneDelegate
        switch phase {
        case .background:
            print("App Scene: en segundo plano")
        case .inactive:
            print("App Scene: inactiva")
        case .active:
            print("App Scene: activa")
            
            // Inicializar Singular
            if let config = self.getConfig() {
                Singular.start(config)
            }
        @unknown default:
            print("App Scene: desconocida")
        }
    }
}

// INICIALIZAR EL SDK EN LAS SIGUIENTES FUNCIONES SCENEDELEGATE
     
// willConnectToSession
- (void)scene:(UIScene *)scene willConnectToSession:(UISceneSession *)session 
  options:(UISceneConnectionOptions *)connectionOptions {
    NSUserActivity* userActivity = [[[connectionOptions userActivities] allObjects] 
      firstObject];
    // Imprimir identificador de vendedor (IDFV) en la consola de Xcode para utilizarlo en la consola de Singular SDK
    NSLog(@"-- Scene Delegate IDFV: %@", [[[UIDevice currentDevice] identifierForVendor] UUIDString]);
    
    // Iniciar una nueva sesión de Singular desde una aplicación en segundo plano
    SingularConfig *config = [self getConfig];
    config.userActivity = userActivity;
    [Singular start:config];
}
    
// continueUserActivity
- (void)scene:(UIScene *)scene continueUserActivity:(NSUserActivity *)userActivity{
  // Inicia una nueva sesión de Singular desde una aplicación en segundo plano.
  SingularConfig *config = [self getConfig];
  config.userActivity = userActivity;
  [Singular start:config];
}
    
// openURLContexts
- (void)scene:(UIScene *)scene openURLContexts:(nonnull NSSet *)URLContexts {
  // Inicia una nueva sesión Singular al arrancar en frío desde el esquema deeplink
  SingularConfig *config = [self getConfig];
  config.openUrl = url;
  [Singular start:config];
  
  // Añada aquí código personalizado para redirigir a enlaces profundos no singulares
  //...
}

// INICIALIZAR EL SDK EN LAS SIGUIENTES FUNCIONES APPDELEGATE
    
// didFinishLaunchingWithOptions
- (BOOL)application:(UIApplication *)application 
  didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // Inicia una nueva sesión cuando el usuario abre la aplicación si se ha agotado el tiempo de espera de la sesión o se ha abierto mediante Singular Link.
    SingularConfig *config = [self getConfig];
    config.launchOptions = launchOptions;
    [Singular start:config];
    return YES;
}
    
// continueUserActivity
- (BOOL)application:(UIApplication *)application 
  continueUserActivity:(NSUserActivity *)userActivity 
    restorationHandler:(void (^)(NSArray<id> *restorableObjects))restorationHandler {
      // Inicia una nueva sesión cuando el usuario abre la aplicación utilizando un Singular Link mientras estaba en segundo plano.
      SingularConfig *config = [self getConfig];
      config.userActivity = userActivity;
      [Singular start:config];
      return YES;
}
    
// openURL
- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url 
  options:(NSDictionary<UIApplicationOpenURLOptionsKey, id> *)options{
    // Inicia una nueva sesión cuando el usuario abre la aplicación utilizando un enlace no Singular, como un esquema de aplicación tradicional.
    SingularConfig *config = [self getConfig];
    config.openUrl = url;
    [Singular start:config];
    // Añadir código personalizado aquí para redirigir a enlaces profundos no Singular
    //...
    return YES;
}

2.7. Envío del ID de usuario a Singular (opcional)

Puede enviar su ID de usuario interno a Singular utilizando un método del SDK de Singular.

• El ID de usuario puede ser cualquier identificador y no debe exponer PII (Personally Identifiable Information). Por ejemplo, no debe utilizar la dirección de correo electrónico, el nombre de usuario o el número de teléfono de un usuario. Singular recomienda utilizar un valor hash único sólo para sus datos de origen.
• El valor de ID de usuario que se pasa a Singular también debe ser el mismo ID de usuario interno que se captura en todas las plataformas (Web/Móvil/PC/Consola/Offline).
• Singular incluirá el ID de usuario en las exportaciones a nivel de usuario, ETL y devoluciones internas de BI (si está configurado). El ID de usuario es un dato de origen y Singular no lo comparte con terceros.
• El valor del ID de usuario, cuando se establece con el método Singular SDK, persistirá hasta que se desactive utilizando el método unsetCustomUserId o hasta que se desinstale la aplicación. Cerrar o reiniciar la aplicación no anula el ID de usuario.

Para establecer el ID de usuario, utilice el método setCustomUserId. Para desactivarlo (por ejemplo, si el usuario "cierra sesión" en la cuenta), llame a unsetCustomUserId.

Si ya conoce el ID de usuario cuando se abre la aplicación, llame a setCustomUserId antes de inicializar Singular SDK. De esta forma, Singular puede tener el ID de usuario desde la primera sesión. Sin embargo, el ID de usuario no suele estar disponible hasta que el usuario se registra o realiza un inicio de sesión. En ese caso, llame a setCustomUserId una vez finalizado el flujo de registro.

setCustomUserId("custom_user_id")
unsetCustomUserId() 

[Singular setCustomUserId:@"a_user_id"];
[Singular unsetCustomUserId];

setDeviceCustomUserId("custom_user_id")

[Singular setDeviceCustomUserId:@"a_user_id"];

2.8. Implementación de propiedades globales (opcional)

Singular SDK permite definir propiedades personalizadas que se enviarán a los servidores de Singular junto con cada sesión y evento enviado desde la aplicación. Estas propiedades pueden representar cualquier información que desee sobre el usuario, el modo/estado de la aplicación o cualquier otra cosa.

Puedes definir hasta 5 propiedades globales. Persisten entre ejecuciones de la aplicación (con el último valor que les haya dado) hasta que las desactive o el usuario desinstale la aplicación.

Casos de uso

Algunos casos de uso para las propiedades globales son:

• Pasar un identificador desde un SDK de terceros y luego usarlo en un postback desde Singular a dicho tercero para propósitos de emparejamiento.
• En una app de juegos, puedes definir una propiedad llamada "Nivel" y establecerla inicialmente a "0". Cualquier sesión y evento enviado desde la app se enviará con "Level": "0". Una vez que el usuario suba de nivel, restableces la propiedad a "1" y así sucesivamente.

Configuración de propiedades globales a través del objeto Config

Para establecer propiedades globales antes de inicializar el SDK, utilice el método setGlobalProperty en el objeto Config.

Tenga en cuenta que como las propiedades globales y sus valores persisten entre ejecuciones de la aplicación, la propiedad que está configurando puede estar ya configurada con un valor diferente. Utilice el parámetro overrideExisting para indicar al SDK si debe anular una propiedad existente con el nuevo valor o no.

 func getConfig() -> SingularConfig? {         
              // (Opcional) Obtenga identificadores de terceros para configurar en Propiedades globales: 
              // Si los SDK de terceros proporcionan identificadores a Singular, 
              // el SDK respectivo debe inicializarse antes de Singular.     
              let thirdPartyKey = "anonymousID"     
              let thirdPartyID = "2ed20738-059d-42b5-ab80-5aa0c530e3e1"     
          
              // Opciones de configuración singulares     
              guard let config = SingularConfig(apiKey: Constants.APIKEY, 
                  andSecret: Constants.SECRET)
              else {         
                  return nil
              }     
              ...     
              // Uso de la función Singular Global Properties para capturar identificadores de terceros
              config.setGlobalProperty(thirdPartyKey, withValue:
                  thirdPartyID, overrideExisting: true)     
              ...
              return config 
          }

- (SingularConfig *)getConfig {     
              // (Opcional) Obtenga identificadores de terceros para configurar en Propiedades globales:
              // Si los SDK de terceros proporcionan identificadores a Singular,
              // el SDK respectivo debe inicializarse antes de Singular.    
              NSString* thirdPartyKey = @"anonymousID";
              NSString* thirdPartyID = @"2ed20738-059d-42b5-ab80-5aa0c530e3e1";     
              
              // Opciones de configuración singulares     
              SingularConfig* config = [[SingularConfig alloc] initWithApiKey:APIKEY 
                  andSecret:SECRET];
              ...
              
              // Uso de la función Singular Global Properties para capturar identificadores de terceros    
              [config setGlobalProperty:thirdPartyKey withValue:thirdPartyID
                  overrideExisting:YES];
              ...
              return config;
          }

Establecer propiedades globales después de la inicialización

Utiliza los siguientes métodos para establecer, desestablecer y recuperar propiedades globales en cualquier momento de la ejecución de la aplicación.

var result = Singular.setGlobalProperty("propertyName",
              andValue: "propertyValue", overrideExisting: true)

BOOL result = [Singular setGlobalProperty:@"propertyName"
              andValue:@"propertyValue" overrideExisting:YES];

var globalProperties = Singular.getGlobalProperties()

NSDictionary* globalProperties = [Singular getGlobalProperties];

Singular.unsetGlobalProperty("propertyName")

[Singular unsetGlobalProperty:@"propertyName"];

Singular.clearGlobalProperties()

[Singular clearGlobalProperties];

2.9. Modificación del tiempo de espera de la sesión (opcional)

Por defecto, si la aplicación se ejecuta en segundo plano durante 60 segundos o más antes de volver al primer plano, el SDK registrará una nueva sesión. Para modificar este valor de tiempo de espera, utilice el método setSessionTimeout y añádalo al archivo Config.

 func getConfig() -> SingularConfig? {       
              // Opciones de configuración singulares     
              guard let config = SingularConfig(apiKey: Constants.APIKEY, andSecret:
                  Constants.SECRET) else {         
                  return nil     
              }     
              ...     
              Singular.setSessionTimeout(120)      
              ...     
              return config
          } 

 - (SingularConfig *)getConfig {
              // Opciones de configuración singulares     
              SingularConfig* config = [[SingularConfig alloc] initWithApiKey:APIKEY 
                  andSecret:SECRET];
              ...     
              [Singular setSessionTimeout:120];
              ...     
              return config;
          }

3. Seguimiento de Eventos e Ingresos

3.1. Seguimiento de eventos (no ingresos)

Singular puede recopilar datos sobre eventos dentro de la aplicación para ayudar a analizar el rendimiento de sus campañas y medir los KPI.Por ejemplo, su organización puede querer recopilar datos sobre inicios de sesión de usuarios, registros, finalización de tutoriales o subidas de nivel en una aplicación de juegos.

La lista de eventos enviados a Singular (con los atributos que los acompañan) debe ser recopilada por el equipo de UA/marketing/negocio basándose en sus KPI de marketing.

Para obtener más información sobre la planificación de eventos de usuario, consulte ¿Seguirá la aplicación los eventos de usuario?en la guía Planificación y requisitos previos del SDK.

En su código, envíe eventos estándar a Singular utilizando los métodos event o eventWithArgs.

Singular.event(EVENT_SNG_LOGIN);

[Singular event:EVENT_SNG_LOGIN];

dic[ATTRIBUTE_SNG_ATTR_CONTENT_TYPE] = "PrivacyController"
dic[ATTRIBUTE_SNG_ATTR_CONTENT_ID] = "0"
dic[ATTRIBUTE_SNG_ATTR_CONTENT] = "GDPR and CCPA Opt-Out Options"
Singular.event(EVENT_SNG_CONTENT_VIEW, withArgs: dic)

NSMutableDictionary *dic = [[NSMutableDictionary alloc] init];
[dic setValue:@"PrivacyController" forKey:ATTRIBUTE_SNG_ATTR_CONTENT_TYPE];
[dic setValue:@"0" forKey:ATTRIBUTE_SNG_ATTR_CONTENT_ID];
[dic setValue:@"GDPR and CCPA Opt-Out Options" forKey:ATTRIBUTE_SNG_ATTR_CONTENT];
[Singular event:EVENT_SNG_CONTENT_VIEW withArgs:dic];

3.2. Seguimiento de ingresos

Singular puede recopilar datos sobre los ingresos obtenidos a través de la aplicación para ayudar a analizar el rendimiento y el ROI de sus campañas. Singular hará que los datos estén disponibles en informes, exportación de registros y postbacks.

Notificación de ingresos a través del seguimiento de IAP (recomendado)

Para notificar eventos de ingresos a Singular, utilice el método iapComplete SDK. Este método envía un evento de ingresos IAP(In-App Purchase de Apple) a Singular con:

• Todos los detalles de la transacción, que Singular utilizará para enriquecer los informes.
• El recibo de la transacción, que puede utilizarse para validar la transacción y analizar o prevenir intentos de fraude.

// *** Obtenga el objeto de transacción SKPaymentTransaction* ***
let transaction:SKPaymentTransaction = ...
          
// Enviar un evento de transacción a Singular sin un nombre de evento personalizado
Singular.iapComplete(transaction)
          
// Enviar un evento de transacción a Singular con un nombre de evento personalizado
Singular.iapComplete(transaction, withName:"MyCustomRevenue")

// *** Obtenga el objeto de transacción SKPaymentTransaction* ***
SKPaymentTransaction* transaction = ...;
          
// Enviar un evento de transacción a Singular sin un nombre de evento personalizado
[Singular iapComplete:transaction];
          
// Enviar un evento de transacción a Singular con un nombre de evento personalizado
[Singular iapComplete:transaction withName:@"MyCustomRevenue"];

Notificación alternativa de eventos de ingresos

Aunque Singular recomienda utilizar iapComplete, también proporcionamos dos métodos alternativos para informar de eventos de ingresos a Singular, en caso de que su aplicación no utilice el seguimiento de IAP de App Store.

// Ingresos sin detalles del producto
          Singular.revenue("USD",amount:1.99)
          
          // Ingresos con detalles del producto
          Singular.revenue("EUR",amount:5.00, productSKU:"SKU1928375", 
              productName:"Reservation Fee",productCategory:"Fee", productQuantity:1, productPrice:5.00)
          
          // Enviar un evento de ingresos con atributos en un diccionario
          var dic: [AnyHashable : Any] = [:]
          dic[ATTRIBUTE_SNG_ATTR_ITEM_DESCRIPTION] = "100% Organic Cotton Mixed Plaid Flannel Shirt"
          dic[ATTRIBUTE_SNG_ATTR_ITEM_PRICE] = "$69.95"
          dic[ATTRIBUTE_SNG_ATTR_RATING] = "5 Star"
          dic[ATTRIBUTE_SNG_ATTR_SEARCH_STRING] = "Flannel Shirt"
          Singular.revenue("USD", amount: 19.95, withAttributes: dic)

// Ingresos sin detalles del producto
          [Singular revenue:@"USD" amount:1.99];
          
          // Ingresos con detalles del producto
          [Singular revenue:@"EUR" amount:5.00 productSKU:@"SKU1928375"
              productName:@"Reservation Fee" productCategory:@"Fee" productQuantity:1 productPrice:5.00];
          
          // Enviar un evento de ingresos con atributos en un diccionario
          NSMutableDictionary *dic = [[NSMutableDictionary alloc] init];
          [dic setValue:@"100% Organic Cotton Mixed Plaid Flannel Shirt"
              forKey:ATTRIBUTE_SNG_ATTR_ITEM_DESCRIPTION];
          [dic setValue:@"$69.95" forKey:ATTRIBUTE_SNG_ATTR_ITEM_PRICE];
          [dic setValue:@"5 Star" forKey:ATTRIBUTE_SNG_ATTR_RATING];
          [dic setValue:@"Flannel Shirt" forKey:ATTRIBUTE_SNG_ATTR_SEARCH_STRING];
          [Singular revenue:@"USD" amount:19.99 withAttributes:dic];

// Ingresos con un nombre personalizado y sin detalles del producto
          Singular.customRevenue("MyCustomRevenue", currency:"USD", amount:1.99)
          
          // Ingresos con un nombre personalizado y detalles del producto
          Singular.customRevenue("MyCustomRevenue", currency:"EUR", amount:5.00, productSKU:"SKU1928375",
              productName:"Reservation Fee", productCategory:"Fee", 
              productQuantity:1, productPrice:5.00)
          
          // Enviar un evento de ingresos personalizado con atributos en un diccionario
          var dic: [AnyHashable : Any] = [:]
          dic[ATTRIBUTE_SNG_ATTR_ITEM_DESCRIPTION] = "100% Organic Cotton Mixed Plaid Flannel Shirt"
          dic[ATTRIBUTE_SNG_ATTR_ITEM_PRICE] = "$69.95"
          dic[ATTRIBUTE_SNG_ATTR_RATING] = "5 Star"
          dic[ATTRIBUTE_SNG_ATTR_SEARCH_STRING] = "Flannel Shirt"
          Singular.customRevenue("CustomRevenueWithArgsDic", currency: "USD",
              amount: 44.99, withAttributes: dic)

// Ingresos con un nombre personalizado y sin detalles del producto
          [Singular customRevenue:@"MyCustomRevenue" currency:@"USD" amount:1.99];
          
          // Ingresos con un nombre personalizado y detalles del producto
          [Singular customRevenue:@"MyCustomRevenue" currency:@"EUR" amount:5.00 productSKU:@"SKU1928375"
              productName:@"Reservation Fee" productCategory:@"Fee"  productQuantity:1 productPrice:5.00];
          
          // Enviar un evento de ingresos personalizado con atributos en un diccionario
          NSMutableDictionary *dic = [[NSMutableDictionary alloc] init];
          [dic setValue:@"100% Organic Cotton Mixed Plaid Flannel Shirt" forKey:ATTRIBUTE_SNG_ATTR_ITEM_DESCRIPTION];
          [dic setValue:@"$69.95" forKey:ATTRIBUTE_SNG_ATTR_ITEM_PRICE];
          [dic setValue:@"5 Star" forKey:ATTRIBUTE_SNG_ATTR_RATING];
          [dic setValue:@"Flannel Shirt" forKey:ATTRIBUTE_SNG_ATTR_SEARCH_STRING];
          [Singular customRevenue:@"MyCustomRevenue" currency:@"USD" amount:44.99 withAttributes:dic];

3.3. Seguimiento de Eventos Híbrido (Avanzado)

Singular recomienda enviar todos los eventos e ingresos a través del SDK de Singular integrado en su app. Sin embargo, Singular puede recoger eventos e ingresos de otras fuentes.

Cualquier evento NO enviado desde el SDK de Singular debe cumplir con los requisitos de documentación de eventos de servidor a servidor de Singular y proporcionar el identificador de dispositivo correspondiente para atribuir correctamente un evento.

Guías de seguimiento de eventos híbridos

4. Opciones Avanzadas

4.1. Creación de enlaces de referencia cortos

Utilice el método createReferrerShortLink para generar un enlace acortado para que el usuario comparta la aplicación con sus amigos. Defina los detalles del usuario remitente en el código de su aplicación cuando se cree el enlace. Esto permite realizar un seguimiento de las atribuciones del remitente en los informes.

Para crear unenlace acortado

1. Cree un Enlace Personalizado Singular con enlaces profundos definidos, que lleve a la descarga de su aplicación (consulte las Preguntas Frecuentes sobre Enlaces Singulares). Este enlace se denominará enlace base en el código siguiente.
2. Cualquier parámetro de anulación de campaña para añadir al enlace dinámicamente (consulte Parámetros de enlace de seguimiento para ver la lista de opciones).
3. El nombre y el ID del usuario remitente, para realizar un seguimiento de las nuevas instalaciones de la aplicación hasta el usuario que compartió el enlace.

Utilice el método createReferrerShortLink para generar el enlace corto como en el ejemplo siguiente.

// 1. Definir variables para el enlace corto de referencia.
                
        // Defina su enlace de seguimiento Singular para utilizarlo como enlace base:
        let referrerBaseLink = "https://yourdomain.sng.link/Csfge/aknl?_dl=myscheme%3A%2F%2Fmydeeplink/referrer&_smtype=3";
        
        // Add your Referrer ID and Name
        let referrerID = referrerIDField.text;
        let referrerName = referrerNameField.text;
        
        // Personalice cualquier parámetro de transferencia
        let passthroughParams = [
            "channel": "sms"
        ]
            
        // 2. Llame al Referrer ShortLink para obtener su enlace corto y compartirlo en las redes sociales
        Singular.createReferrerShortLink(referrerBaseLink, referrerName: referrerName, 
            referrerId: referrerID, passthroughParams: passthroughParams, completionHandler: {(shortLink, error) in
            if error != nil {
                // Lógica para reintentar/abortar/modificar los parámetros pasados a la función, según la causa del error
            }
            if (shortLink != nil || shortLink != "") {
                // Agregue su lógica de compartir aquí:
                ....
            }
        })

 
        // 1. Definir variables para el enlace corto de referencia.
        
        // Defina su enlace de seguimiento Singular para utilizarlo como enlace base:
        NSString* referrerBaseLink = @"https://yourdomain.sng.link/Csfge/aknl?_dl=myscheme%3A%2F%2Fmydeeplink/referrer&_smtype=3";
        
        // Add your Referrer ID and Name
        NSString* referrerID = self.referrerIDField.text;
        NSString* referrerName = self.referrerNameField.text;
        
        // Personalice cualquier parámetro de transferencia
        NSDictionary* passthroughParams = @{@"channel": @"sms"};
        
        // 2. Llame al Referrer ShortLink para obtener su enlace corto y compartirlo en las redes sociales
        [Singular createReferrerShortLink:referrerBaseLink
            referrerName:referrerName
            referrerId:referrerID
            passthroughParams:passthroughParams
            completionHandler:^(NSString *shortLink, NSError *error) {
                if (error) {
                    // Lógica para reintentar/abortar/modificar los parámetros pasados a la función, según la causa del error
                }
                if (shortLink) {
                    // Agregue su lógica de compartir aquí:
                    ...
                }
            }
        ];

4.2. Añadir soporte de atribución de ingresos publicitarios

4.3. Seguimiento de desinstalaciones

Para configurar el seguimiento de desinstalaciones

1. Habilite la app en Singular siguiendo la guía: Configuración del seguimiento de instalaciones de iOS.
2. En la app, envíe a Singular el token de dispositivo devuelto por el servicio de notificaciones push de Apple (APNS). Para pasar el token de dispositivo a Singular, utilice el método registerDeviceTokenForUninstall o registerDeviceToken. Hágalo antes de inicializar Singular SDK. Debe llamarse desde el método didRegisterForRemoteNotificationsWithDeviceToken del AppDelegate.

func application(_ application: UIApplication, 
        didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
        // Envíe el deviceToken a Singular para realizar un seguimiento de la desinstalación     
        Singular.registerDeviceToken(forUninstall: deviceToken) 
    } 

 - (void)application:(UIApplication*)application
        didRegisterForRemoteNotificationsWithDeviceToken:(NSData*)deviceToken {     
        // Envíe el deviceToken a Singular para realizar un seguimiento de la desinstalación      
        [Singular registerDeviceTokenForUninstall:deviceToken];
    }

4.4. Interfaz JavaScript de Singular SDK

Singular proporciona una interfaz JavaScript que puede utilizar para llamar a Singular en su aplicación.

Por ejemplo, si configura la interfaz JavaScript, puede enviar eventos a Singular desde código JavaScript de la siguiente manera:

Singular.event('event');
Singular.event('test', JSON.stringify({"a1":"bar", "a2":"boo", "a3":"baz"}));

Métodos compatibles en JavaScript

La interfaz admite los siguientes métodos del SDK:

• setCustomUserID
• unsetCustomUserID
• event
• revenue

Activación de la interfaz JavaScript

Para habilitar la interfaz JavaScript al utilizar WKWebView, debe añadir código al método webView del protocolo WKNavigationDelegate (este protocolo le ayuda a implementar comportamientos personalizados que se activan cuando una vista web gestiona una solicitud de navegación).

extension ViewController: WKNavigationDelegate { 
    func webView(_: WKWebView, decidePolicyFor: WKNavigationAction, 
      decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) { 
      // Manipulador singular
      let js = "typeof(Singular)" 
       webView.evaluateJavaScript(js) { (result, error) -> Void in 
         if let resultString = result as? String { 
           if resultString.isEqual("undefined") { 
             do { 
               let contents = try String(contentsOfFile: 
               Bundle.main.path(forResource: "Singular", ofType: "js")!) 
               self.webView.evaluateJavaScript(contents, completionHandler: nil) 
             } catch { } 
           }
           else { 
             print(decidePolicyFor.request) 
             Singular.processJSRequestWK(self.webView, withURL:decidePolicyFor.request) 
           } 
         }  
       } 
       // el resto de tu código va aquí   
    }
  }

5. Cumplimiento de las leyes de privacidad de datos

Singular proporciona una funcionalidad de protección de la privacidad para ayudarle a cooperar con cualquier socio que pueda estar cumpliendo con las leyes de privacidad del consumidor, como GDPR y CCPA(California Consumer Privacy Act). Estos socios quieren ser notificados si el usuario final ha dado su consentimiento para compartir su información privada.

5.1. Limitar el uso compartido de datos

Si ha implementado una forma de solicitar a los usuarios su consentimiento para compartir su información, utilice el método limitDataSharing para notificar a Singular la elección del usuario:

• Utilice limitDataSharing:NO para indicar que el usuario ha dado su consentimiento (optado) para compartir su información.
• Utilice limitDataSharing: YES si el usuario no dio su consentimiento.

Singular utiliza LimitDataSharing en los"Postbacks de Privacidad del Usuario", así como en la transmisión de esta información a socios que la requieren para cumplir con la normativa pertinente. Consulte "Privacidad del usuario y Limitar el uso compartido de datos" para obtener más información.

// El usuario ha optado por compartir
data Singular.limitDataSharing(false) 

// El usuario ha optado por compartir
[Singular limitDataSharing:NO];

5.2. Métodos adicionales para el cumplimiento de GDPR

Singular SDK proporciona varios métodos para ayudarle a cumplir con las políticas GDPR y permitir que Singular conozca el consentimiento o no consentimiento del usuario para el seguimiento.

Singular.trackingOptIn() 

[Singular trackingOptIn]; 

Singular.stopAllTracking() 

[Singular stopAllTracking]; 

Singular.resumeAllTracking() 

[Singular resumeAllTracking]; 

Singular.isAllTrackingStopped()
// Devuelve verdadero / falso

[Singular isAllTrackingStopped];
// Devuelve verdadero / falso

6. Preguntas Frecuentes y Problemas

Consulte esta sección si encuentra algún problema o error al crear su aplicación de prueba.