Guía de integración de iOS SDK

 

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.

Instalación del SDK mediante CocoaPods
  1. Descargue e instale la última versión de CocoaPods.
  2. Para crear un archivo podfile, vaya a la carpeta raíz del proyecto en el Terminal y escriba:

    pod init
  3. Para añadir la dependencia de Singular SDK, añada lo siguiente al Podfile de su proyecto:

    pod 'Singular-SDK'

    Por ejemplo

    pod_for_swiftcocoapods.png

  4. En su Terminal, navegue hasta la carpeta raíz del proyecto y ejecute:

    pod install
  5. A partir de este momento, abra el archivo del espacio de trabajo de Xcode .xcworkspace para abrir el proyecto, en lugar del archivo .xcodeproj.
  6. Cree una cabecera puente Swift siguiendo las instrucciones que se indican a continuación.
Instalación del SDK mediante el gestor de paquetes Swift
  1. En Xcode, ve a Archivo > Añadir paquetes y entra en el repositorio de GitHub de Singular SDK:

    https://github.com/singular-labs/Singular-iOS-SDK

    update_sdk_version_1.png

  2. Actualiza la versión de Singular SDK:

    update_sdk_version_2.png

  3. Haz clic en el botón Añadir Paquete.
  4. Ve a Build Phases > Link Binary with Libraries y añade la librería AdServices. framework. Asegúrate de marcarla como Optional ya que sólo está disponible para dispositivos con iOS 14.3 y superior.

    link_binary_adservices.png

  5. Vaya a Build Settings > Linking > Other Linker Flags y actualice Other Linker Flags con los siguientes elementos:

    frameworks.png

    other_linker_flags.png

  6. Cree una cabecera puente Swift siguiendo las instrucciones que se indican a continuación.
Instalación del Framework SDK Singular (Librería Estática)

La descarga e instalación de Singular Framework sólo es necesaria si NO está utilizando el método CocoaPods o SPM anterior.

¿Está actualizando desde Singular SDK 12.3.2 o inferior?

Siga los pasos que se indican a continuación para eliminar la antigua biblioteca estática

  1. Vaya a los archivos del proyecto y elimine la biblioteca estática de Singular. Normalmente, debería tener una carpeta llamada algo así como Singular-iOS-sdk-v12.3.2. Haga clic con el botón derecho en la carpeta y elimínela del proyecto.
  2. Proceda a la siguiente sección para instalar el nuevo Framework

Añadir Singular Framework por primera vez

  1. Descargue y descomprima el SDK Framework.

    Seleccione el Framework correcto para su implementación:

  2. Añada la carpeta descomprimida a una carpeta de su proyecto Xcode:

    En Xcode, haga clic con el botón derecho en Your App Name > Add Files To [Your Project Name]. En el cuadro de diálogo que se abre, seleccione Options > Create Groups y añada la carpeta donde descomprimió el SDK.





    El framework Singular debería estar ahora en tu proyecto

  3. Para añadir las librerías necesarias

    • En Xcode, selecciona Build Phases > Link Binary With Libraries.
    • Haz clic en + y añade las siguientes bibliotecas:

      Libsqlite3.0.tbd
      SystemConfiguration.framework
      Security.framework
      Libz.tbd
      AdSupport.framework
      WebKit.framework
      StoreKit.framework
      AdServices.framework (marcar como Opcional ya que sólo está
      disponible para dispositivos con iOS 14.3 y superior.).
  4. Integrar y firmar Singular Framework
    • Vaya a General > Marcos de trabajo, bibliotecas y contenido integrado.
    • Ajustar el Singular Framework para que sea "Embed & Sign" (incrustar y firmar)

Añadir el encabezado Swift Bridging

Si ha instalado el SDK mediante CocoaPods o el gestor de paquetes de Swift, debe crear un encabezado de puente para que Swift utilice las bibliotecas Obj-C del SDK de Singular.

  1. En su proyecto, cree un nuevo archivo de tipo Header , y nómbrelo YourProjectName-Bridging-Header.

    new_header_file.png

  2. Abra el archivo y añada lo siguiente:

    #import <Singular/Singular.h>

    Por ejemplo

    swift_cocoapods_import_singular.png

  3. Ve a Build Settings > Objective-C BridgingHeader y añade la ruta relativa del archivo:

    objective_c_bridging_header.png

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

Importante:

  • Para utilizar Swift, debe disponer de un Bridging Header (consulte la guía anterior).
  • Si ha añadido Singular SDK utilizando el gestor de paquetes Swift, asegúrese de actualizar Build Settings > Other Linker Flags como se explica más arriba.

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

SwiftObjective-C
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
      }

Nota: A partir de la versión 12.0.6 del SDK de Singular iOS, SKAdNetwork está activado por defecto.

Si todavía está usando una versión anterior del SDK, necesita habilitar SKAdNetwork usando el siguiente código cuando cree el objeto de configuración:

SwiftObjective-C
// Habilite SKAdNetwork en modo administrado
config.skAdNetworkEnabled = true

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)

Aprenda a utilizar SKAdNetwork en modo manual

Si desea actualizar el valor de conversión por su cuenta utilizando el código de la app, primero debe establecer el flag manualSkanConversionManagement en el Singular Config. Esto le permite utilizar varios métodos del SDK para recuperar y actualizar el valor de conversión manualmente.

Para activar el Modo Manual:

SwiftObjective-C
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
      }

Para actualizar el valor de conversión:

En Modo Manual, para actualizar el valor de conversión, necesita utilizar el método skanUpdateConversionValue. Puedes usarlo donde sea necesario en el ciclo de vida de tu aplicación.

Nota: El método skanUpdateConversionValue no funcionará si no has habilitado manualSkanConversionManagement.

Método skanUpdateConversionValue
Descripción Actualiza manualmente el valor de conversión de SKAdNetwork.
Firma (BOOL)skanUpdateConversionValue:(NSInteger)conversionValue;
Ejemplo de uso
SwiftObjective-C
// 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)

Otros métodos de SKAdNetwork:

Para obtener el valor de conversión actual, utilice el método skanGetConversionValue o conversionValueUpdatedCallback. Ambos funcionan en Modo Gestionado y Manual.

Método skanGetConversionValue
Descripción Obtiene el valor de conversión actual rastreado por Singular SDK.
Firma (NSNumber *)skanGetConversionValue;
Ejemplo de uso
SwiftObjective-C
let conversionValue = Singular.skanGetConversionValue()
conversionValueUpdatedCallback Devolución de llamada
Descripción Obtiene el valor de conversión actual rastreado por Singular SDK.
Firma void(^conversionValueUpdatedCallback)(NSInteger);
Ejemplo de uso
SwiftObjective-C
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
      } 

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.

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

Consejo: Cuando se establece un retardo de inicialización, el flujo de la app es el siguiente:

  1. Cuando la app se abre, el Singular SDK comienza a grabar una sesión y eventos de usuario pero no los envía al servidor Singular todavía.
  2. Cuando se concede/deniega el consentimiento de App Tracking Transparency, o transcurre el tiempo establecido, el SDK envía la sesión y cualquier evento en cola al servidor de Singular (con o sin el IDFA).
  3. Singular inicia entonces el proceso de atribución, aprovechando el IDFA si está disponible.
Conozca todos los escenarios posibles de ATT

La siguiente tabla resume los posibles escenarios utilizando esta integración:

Escenario Disponibilidad de IDFA
El usuario ve el diálogo de consentimiento y otorga su consentimiento antes de que transcurra el tiempo establecido. El IDFA está disponible
El usuario ve el diálogo de consentimiento y lo deniega antes de que transcurra el tiempo establecido. IDFA no está disponible
El tiempo establecido expira, entonces el usuario ve el diálogo de consentimiento y otorga su consentimiento. IDFA está disponible sólo para los eventos de usuario que se reportan después de que se otorga el consentimiento
El tiempo establecido expira, entonces al usuario se le muestra el diálogo de consentimiento y niega el consentimiento. IDFA no está disponible
Al usuario se le muestra el diálogo de consentimiento, sale de la aplicación sin realizar ninguna acción, y más tarde abre la aplicación y otorga el consentimiento después de que el tiempo establecido haya expirado. Los eventos en cola se envían al servidor Singular cuando se vuelve a abrir la aplicación. El IDFA no está disponible para estos eventos. Cualquier evento registrado después de que se conceda el consentimiento tiene IDFA asociado.
Al usuario se le muestra el diálogo de consentimiento, sale de la aplicación sin realizar ninguna acción, y más tarde abre la aplicación y deniega el consentimiento. Los eventos en cola se envían a los servidores de Singular cuando se vuelve a abrir la aplicación. El IDFA no está disponible para estos eventos ni para ninguno de los eventos rastreados posteriormente.

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.

Notas:

  • Si la aplicación ya está configurada para utilizar iOS Universal Links, el dominio Universal Link ya existe en Dominios asociados y puede permanecer. Este dominio debe añadirse a la opción de configuración Dominios admitidos, como se indica en la siguiente sección.
  • También debe incluir el dominio de enlace personalizado de Singular, para que Singular pueda realizar un seguimiento de las atribuciones de las campañas de marketing y gestionar los enlaces profundos de estas campañas.

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.

SwiftObjective-C
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í
      }

Otras Opciones de Enlace

2.6. Inicialización de Singular

Consejo: Antes de continuar, ¡asegúrese de haber completado los pasos siguientes!

  • Añadida la biblioteca de Singular
  • Si utiliza swift: creado un Swift Bridging Header
  • Añadido código para crear el objeto Singular Config
  • Añadido un gestor de enlaces profundos
  • Habilitado SKAdNetwork
  • Si se muestra el ATT: añadido waitForTrackingAuthorizationWithTimeoutInterval
  • La aplicación se ha compilado correctamente (la aplicación debería compilarse sin errores en esta fase).

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

Para iOS 13+ (Swift SceneDelegate)
// 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 //... }
Para iOS 13+ (Interfaz SwiftUI)
// 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") } } }
Para iOS 13+ (Objective-C SceneDelegate)
// 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 //... }
Para versiones anteriores de iOS (Objective-C AppDelegate)
// 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; }

Notas:

  • Al crear el objeto config, tenga cuidado de pasar la opción correcta - userActivity o openUrl. Consulte el código de ejemplo a continuación y consulte las aplicaciones de ejemplo si es necesario.
  • Recuerde cumplir las distintas leyes de privacidad promulgadas en las regiones en las que realiza negocios, incluidas GDPR, CCPA y COPPA. Para obtener más información, consulte SDK Opt-In and Opt-Out Practicesy revise las funciones de Singular SDK que le ayudan a cumplir con las leyes de privacidad de datos.
  • Para inicializar el SDK, necesita su Clave SDK de Singular y su Secreto SDK. Puede obtenerlas en la plataforma Singular en "Developer Tools > SDK Integration > SDK Keys".

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.

Nota: Si utiliza la solución multidispositivo de Singular, debe recopilar el ID de usuario en todas las plataformas.

  • 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.

Nota: Si varios usuarios utilizan un único dispositivo, recomendamos implementar un flujo de cierre de sesión para establecer y desestablecer el ID de usuario para cada inicio y cierre de sesión.

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.

Métodos setCustomUserId y unsetCustomUserId
Descripción Establece y desestablece el ID de usuario.
Firma (void)setCustomUserId:(NSString*)customUserId
(void)unsetCustomUserId;
Ejemplo de uso
SwiftObjective-C
setCustomUserId("custom_user_id")
unsetCustomUserId()
Opcional: Asignación de dispositivo de ID de usuario personalizado

Importante: Esta función Enterprise avanzada sólo está disponible en casos excepcionales. Consulte con uno de los ingenieros de soluciones de Singular antes de implementarla.

Singular puede recibir datos adicionales de seguimiento de eventos móviles a través de una integración de servidor a servidor. Para utilizar esta función, debe asignar el ID de usuario al identificador de seguimiento de dispositivos móviles de Singular.

Nota: Llame a este método tan pronto como sea posible después de inicializar el SDK de Singular o una vez que tenga el ID de usuario.

Método setDeviceCustomUserId
Descripción Establece el Id. de usuario personalizado igual al de inicio de sesión y lo asigna al identificador de seguimiento de Singular.
Firma static void setDeviceCustomUserId(String customUserId)
Ejemplo de uso
SwiftObjective-C
setDeviceCustomUserId("custom_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.

Notas:

  • Las propiedades globales se reflejan actualmente en los registros de eventos a nivel de usuario de Singular (véase Exportación de registros de atribución) y en los postbacks. En el futuro se añadirá soporte para las propiedades globales en los informes agregados de Singular (la página Informes o la API de informes). Si tiene alguna pregunta sobre esta función o está interesado en las actualizaciones de la compatibilidad con propiedades globales, póngase en contacto con su gestor de éxito de clientes de Singular.
  • El nombre y el valor de cada propiedad pueden tener un máximo de 200 caracteres. Si pasa un nombre o valor de propiedad más largo, se truncará a 200 caracteres.

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.

Método setGlobalProperty
Descripción Establece una propiedad global.
Firma (void)setGlobalProperty:(NSString*)key withValue:(NSString*)value overrideExisting:(BOOL)overrideExisiting;
Ejemplo de uso
SwiftObjective-C
 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 }

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.

Notas:

  • Si la propiedad no existe todavía, y ya hay otras 5 propiedades globales, la propiedad no será añadida.
  • Si la propiedad ya ha sido establecida, el parámetro overrideExisting determina si el valor existente será anulado.
  • El método devuelve true si la propiedad se ha establecido correctamente o false en caso contrario.
Método setGlobalProperty
Descripción Establece una propiedad global a un valor dado.
Firma (BOOL) setGlobalProperty:(NSString*)key andValue:(NSString*)value overrideExisting:(BOOL)overrideExisting
Ejemplo de uso
SwiftObjective-C
var result = Singular.setGlobalProperty("propertyName",
              andValue: "propertyValue", overrideExisting: true)
Método getGlobalProperties
Descripción Recupera todas las propiedades globales y sus valores actuales como un Map.
Firma (NSDictionary*) getGlobalProperties
Ejemplo de Uso
SwiftObjective-C
var globalProperties = Singular.getGlobalProperties()
Método unsetGlobalProperty
Descripción Elimina una propiedad global.
Firma (void) unsetGlobalProperty:(NSString*)clave
Ejemplo de uso
SwiftObjective-C
Singular.unsetGlobalProperty("propertyName")
Método clearGlobalProperties
Descripción Elimina todas las propiedades globales.
Firma (void) clearGlobalProperties
Ejemplo de uso
SwiftObjective-C
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.

Método setSessionTimeout
Descripción Cambia el valor del tiempo de espera de la sesión.
Firma (void)setSessionTimeout:(int)timeout
Ejemplo de Uso
SwiftObjective-C
 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
          } 

3. Seguimiento de Eventos e Ingresos

Nota : 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.

Nota : Recomendamos enviar todos los eventos de la aplicación al servidor de Singular utilizando los métodos de Singular SDK en su aplicación. Si planea enviar eventos a Singular desde otro proveedor o un servidor interno, consulte la sección Seguimiento de eventos híbridos a continuación.

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.

Nota: para los eventos estándar, utilice el nombre iOS del eventotal y como aparece en la lista de eventos y atributos estándar del SDK de iOS, por ejemplo, EVENT_SNG_LOGIN.

Para los eventos personalizados, eventos que su organización desea medir y que no coinciden con ninguno de los eventos estándar de Singular, utilice cualquier nombre personalizado (con un máximo de 32 caracteres). Recomendamos utilizar nombres en inglés para que sean compatibles con cualquier red publicitaria asociada que pueda recibir el evento de Singular con fines de optimización.

evento Método
Descripción Envía un evento de usuario a Singular para su seguimiento.
Firma (void)evento:(NSString *)nombre
Ejemplo de uso
SwiftObjective-C
Singular.event(EVENT_SNG_LOGIN);
Método eventWithArgs
Descripción Envía un evento de usuario a Singular para su seguimiento, con información adicional.
Firma (void)eventWithArgs:(NSString *)name, ...
Ejemplo de uso El siguiente ejemplo envía un evento de Content View con los atributos estándar recomendados.
SwiftObjective-C
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)

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.

Nota: Si su aplicación admite el seguimiento de IAP a través de la App Store, se recomienda este método. Si no utiliza IAP de la App Store, consulte los métodos alternativos a continuación.

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.

Notas:

  • Cuando utilice iapComplete, debe incluir el objeto SKPaymentTransaction en el evento.
  • Cualquier ingreso notificado en una divisa diferente se convertirá automáticamente a la divisa preferida de su organización, según lo establecido en su cuenta de Singular.
MétodoiapComplete
Descripción Envía un evento de ingresos a Singular con el recibo de la transacción.
Firma (void)iapComplete:(id)transacción (void)iapComplete:(id)transacción withName:(NSString *)nombre;
Ejemplo de uso
SwiftObjective-C
// *** 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")

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.

Los métodos Revenue y CustomRevenue

Los métodos revenue y customRevenue le permiten especificar manualmente el importe de la transacción y la moneda, así como detalles adicionales opcionales, como el número de serie del producto y la cantidad, etc. El método customRevenue también le permite pasar un nombre de evento personalizado.

Tenga en cuenta que si utiliza estos métodos, Singular no obtiene el recibo de la transacción y no puede validarla.

Nota: Pase la divisa como un código de divisa ISO 4217 de tres letras, por ejemplo, "USD", "EUR", "INR".

ingresos Método
Descripción Envía un evento de ingresos a Singular con el importe y la divisa de los ingresos y detalles adicionales opcionales.
Firma

(void)revenue:(NSString *)moneda importe:(double)importe;

(void)revenue:(NSString *)moneda importe:(double)importe productSKU:(NSString *)productSKU productName:(NSString *)productName productCategory:(NSString *)productCategory productQuantity:(int)productQuantity productPrice:(double)productPrice;

(void)revenue:(NSString *)currency amount:(double)amount withAttributes:(NSDictionary*)attributes;

Ejemplo de uso
SwiftObjective-C
// 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)
Método customRevenue
Descripción Envía un evento de ingresos a Singular con un nombre de evento así como el importe y la moneda de los ingresos y detalles adicionales opcionales.
Firma

(void)customRevenue:(NSString *)eventName currency:(NSString *)currency amount:(double)amount;

(void)customRevenue:(NSString *)eventName currency:(NSString *)currency amount:(double)amount productSKU:(NSString *)productSKU productName:(NSString *)productName productCategory:(NSString *)productCategory productQuantity:(int)productQuantity productPrice:(double)productPrice;

(void)customRevenue:(NSString*)eventname currency:(NSString *)currency amount:(double)amount withAttributes:(NSDictionary*)attributes;

Ejemplo de uso
SwiftObjective-C
// 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)

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.

Importante:

Se producirán discrepancias si los identificadores de dispositivo utilizados en las solicitudes de eventos de servidor a servidor no tienen un identificador de dispositivo coincidente en Singular. Tenga en cuenta las siguientes posibilidades:

  • Si se recibe una solicitud de evento "antes" de que Singular SDK haya registrado el identificador de dispositivo, desde una App Session, entonces la solicitud de evento se considerará la "primera sesión" para el dispositivo desconocido, y Singular atribuirá el dispositivo como una atribución orgánica.
  • Si Singular SDK registró un identificador de dispositivo, pero el identificador de Singular SDK difiere del identificador de dispositivo especificado en la solicitud de evento de servidor a servidor, entonces el evento se atribuirá incorrectamente.

Guías de seguimiento de eventos híbridos

Envío de eventos desde un servidor interno

Singular puede recopilar datos sobre los ingresos de su Servidor para ayudar a analizar el rendimiento y el ROI de sus campañas.

Requisitos:

  • Desde un Evento de Registro o Inicio de Sesión in-app, capture y pase los identificadores de dispositivo y almacene estos datos con el ID de Usuario en su servidor. Dado que los identificadores de dispositivo pueden cambiar para un usuario, asegúrese de actualizar los identificadores cuando un usuario genere una sesión de aplicación. Esto garantiza que el evento del lado del servidor se atribuya al dispositivo correcto.
  • Los eventos del lado del servidor son específicos de cada plataforma y sólo deben enviarse con el identificador de dispositivo que coincida con la plataforma del dispositivo (por ejemplo, IDFA o IDFV para dispositivos iOS).
  • Puede utilizar el mecanismo de postback de Singular Internal BI para enviar un evento en tiempo real a su endpoint interno para que pueda actualizar el conjunto de datos en el lado del servidor. Consulte las Preguntas Frecuentes sobre Postback de BI Interno.
  • Revise la sección "Seguimiento de Ingresos" en la guía de Integración Servidor-a-Servidor para más detalles.
Envío de Eventos desde un Proveedor de Ingresos
Proveedores de terceros como RevenueCat o adapty pueden proporcionar Ingresos por Compras y Suscripciones a Singular.

Siga los siguientes enlaces para obtener más información sobre cómo habilitar a estos socios.

  • Más información en la documentación de RevenueCat.
  • Más información en la documentación de adapty.
Envío de Eventos desde Segmento

Para que Segment pueda enviar eventos a Singular, en paralelo con el SDK de Singular, debe añadir un Destino "Cloud-Mode" en Segment. Siga nuestra guía AQUÍ.

4. Opciones Avanzadas

4.1. Creación de enlaces de referencia cortos

Nota: Esta funcionalidad está disponible en la versión 11.0.8+ del SDK.

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.

Método createReferrerShortLink
Descripción Utilice el método createReferrerShortLink para generar un enlace acortado para que el usuario comparta la aplicación con sus amigos.
Firma (void)createReferrerShortLink:(NSString *)baseLink referrerName:(NSString *)referrerName referrerId:(NSString *)referrerId passthroughParams:(NSDictionary *)passthroughParams completionHandler:(void(^)(NSString *, NSError *))completionHandler;
Ejemplo de uso
SwiftObjective-C
// 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í:
                ....
            }
        })

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

Nota: A partir de la versión 11.0.0 del SDK, Singular añadió la opción de configurar la atribución de ingresos por publicidad a través del SDK de Singular. La atribución de ingresos publicitarios puede seguir configurándose mediante llamadas a la API, sin necesidad de actualizar el SDK de Singular en las aplicaciones. Sin embargo, si desea medir los ingresos publicitarios de las campañas SKAdNetwork, es necesario configurar la atribución de ingresos publicitarios a través del SDK.

Para añadir soporte de atribución de ingresos publicitarios en el SDK de Singular:

  1. Asegúrese de que está utilizando la última versión del SDK de Singular.
  2. Añada el fragmento de código adecuado a su integración de Singular SDK, dependiendo de la plataforma de mediación utilizada para los datos de ingresos publicitarios.

Nota: pase la moneda como un código de moneda ISO 4217 de tres letras, por ejemplo, "USD", "EUR", "INR".

AdMob
  1. Nota : Esta función debe estar activada en su cuenta de Admob.

    Ver https://support.google.com/admob/answer/11322405#getstarted

SwiftObjective-C
var rewardedAd: GADRewardedAd?
GADRewardedAd.load(withAdUnitID: "AD_UNIT_ID", request: request) { 
[weak self] ad, error in guard let self = self else { return } if let error = error { print("El anuncio recompensado no se carga con error: \(error.localizedDescription)") return } self.rewardedAd = ad self.rewardedAd?.paidEventHandler = { adValue in let impressionData = adValue let data = SingularAdData(
adPlatform: "Admob", currency: impressionData.currencyCode, revenue: impressionData.value) }
}
AppLovinMax
  1. Recupera el objeto recibido del evento de AppLovin MAX, didReceivedMessage
SwiftObjective-C
if let message = message {
   let data = SingularAdData(
adPlatform: "AppLovin", currency: "USD", revenue: message.data["revenue"] as? Double ?? 0.0) Singular.adRevenue(data) }
IronSource
  1. Recuperar el objeto recibido del evento de IronSource, impressionDataDidSucceed
  2. Asegúrese que el ARM SDK Postbacks Flag en IronSource está activado.
  3. Ver https://developers.is.com/ironsource-mobile/general/ad-revenue-measurement-postbacks/#step-1
SwiftObjective-C
if let impressionData = impressionData {
   let data = SingularAdData(
adPlatform: "IronSource", currency: "USD", revenue: impressionData.revenue) Singular.adRevenue(data) }
TradPlus
  1. Configure el impressionDelegate
  2. Añadir Singular al Callback TradPlusAdImpression
SwiftObjective-C
TradPlus.sharedInstance().impressionDelegate = self

func tradPlusAdImpression(_ adInfo: [AnyHashable: Any]?) { guard let adInfo = adInfo else { return } let currency = "USD" if let ecpm = adInfo["ecpm"] as? Float { let revenue = CGFloat(ecpm) / 1000.0 let data = SingularAdData(adPlatform: "TradPlus", currency: currency, revenue: revenue) Singular.adRevenue(data) }
}
Otro (Genérico)
  1. Inicializa el objeto SingularAdData con los datos relevantes
  2. Informar de los datos a Singular
SwiftObjective-C
let data = SingularAdData(
adPlatform: "TU_PLATAFORMA_PUBLICITARIA", currency: "CÓDIGO MONEDA", revenue: 9.90) Singular.adRevenue(data)

4.3. Seguimiento de desinstalaciones

Nota : El seguimiento de desinstalaciones sólo está disponible para clientes Enterprise. Además, el seguimiento de desinstalaciones requiere que la aplicación admita notificaciones push. Consulte la guía de Apple para implementar APNS.

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.

Nota: Si ya está recuperando un token de dispositivo de una implementación de notificaciones push existente, puede utilizar ese valor.

El token de APNS suele ser un dato binario en formato nativo. Pasa el token tal y como lo recibiste de APNS. Si la aplicación altera el tipo de datos del token, pásalo como una cadena codificada en hexadecimal, por ejemplo: b0adf7c9730763f88e1a048e28c68a9f806ed032fb522debff5bfba010a9b052

Método registerDeviceTokenForUninstall
Descripción Pasa el token de dispositivo devuelto por APNS.
Firma + (void)registerDeviceTokenParaDesinstalación:(NSData*)deviceToken;
Ejemplo de uso
SwiftObjective-C
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) 
    } 

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:

JavaScript
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

Nota: A partir de iOS 8.0+, Apple recomienda utilizar WKWebView para añadir contenido web a su aplicación. No utilice UIWebView ni WebView. Consulte la documentación de WKWebView de Apple para obtener más información.

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).

Swift
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.

Nota: El uso del método es opcional, pero puede haber información de atribución que el socio compartirá con Singular sólo si se notifica específicamente que el usuario ha optado por ello.

Método limitDataSharing
Descripción Notifica a Singular el consentimiento del usuario (opt-in) para compartir datos privados.
Firma (void)limitDataSharing:(BOOL)shouldLimitDataSharing;
Ejemplo de uso
SwiftObjective-C
// El usuario ha optado por compartir
data Singular.limitDataSharing(false) 

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.

Método trackingOptIn
Descripción Notifica a Singular el consentimiento del usuario para el seguimiento (opt-in).
Firma (void)trackingOptIn;
Ejemplo de uso
SwiftObjective-C
Singular.trackingOptIn() 
Método stopAllTracking
Descripción Detiene todas las actividades de seguimiento de este usuario en esta aplicación.
Firma (void)stopAllTracking;
Ejemplo de uso

Importante: Llamar a este método desactiva el SDK, incluso entre reinicios de la app (el estado es persistente). La única forma de desactivarlo es llamando al método resumeAllTracking.

SwiftObjective-C
Singular.stopAllTracking() 
Método resumeAllTracking
Descripción Reanuda las actividades de seguimiento para este usuario en esta aplicación.
Firma (void)resumeAllTracking;
Ejemplo de uso
SwiftObjective-C
Singular.resumeAllTracking() 
Método isAllTrackingStopped
Descripción Comprueba el estado de las actividades de seguimiento de este usuario en esta aplicación.
Firma (BOOL)isAllTrackingStopped;
Ejemplo de Uso
SwiftObjective-C
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.

¿Por qué recibo un error "Sandbox: rsync.samba(15813) deny(1) file-read-data..."?

En Xcode 15, hay una nueva opción llamada "User Script Sandboxing" que juega un papel crucial en la construcción El propósito es evitar que las secuencias de comandos de hacer cambios no deseados en el sistema, mejorando así la estabilidad y la seguridad de la construcción. Cuando está activada, el sistema de compilación restringe las secuencias de comandos de usuario para no permitir dependencias de entrada/salida no declaradas. Esto es problemático para Singular SDK, ya que necesita ejecutar scripts para vincular dinámicamente las dependencias.

Para resolverel problema

  1. Vaya a Build Settings > Build Options.
  2. Ajuste "User Script Sandboxing" a un valor "No"
¿Por qué recibo un error "No module named Singular"?
  1. Compruebe que se ha creado el Bridging Header.
  2. Validar que el archivo Bridging Header está enlazado en Build Settings > Objective-C Bridging Header.
¿Por qué recibo un error de compilación "Arm64"?

En algunos casos, el simulador de iOS requiere que arm64 se excluya en Build Settings > Excluded Architectures.

excluded_architectures_arm64.png

He implementado las propiedades globales. ¿Por qué no las veo en la consola de pruebas?

Las propiedades globales no se muestran actualmente en la consola de pruebas, pero se añadirán en el futuro. Utilice Export Logs para validar esta funcionalidad.

¿Por qué aparece el siguiente error en la consola de Xcode? "SKAdNetwork: Error al actualizar el valor de conversión: Error Domain=SKANErrorDomain Code=10"?

Puede ignorar este error, ya que es de esperar cuando SKAdNetwork no ha visto ninguna impresión de una campaña (consulte la respuesta de Apple a esta pregunta).

¿Por qué aparece un error de registro?

Los siguientes errores de registro comunes pueden ignorarse:

  • [logging] duplicate column name: singular_link in "ALTER TABLE sessions ADD COLUMN singular_link TEXT DEFAULT NULL"
  • [logging] duplicate column name: payload in "ALTER TABLE sessions ADD COLUMN payload TEXT DEFAULT NULL"
  • [logging] duplicate column name: sequence in "ALTER TABLE events ADD COLUMN sequence INTEGER DEFAULT -1"
  • [logging] duplicate column name: payload in "ALTER TABLE events ADD COLUMN payload TEXT DEFAULT NULL"