Documento

SDK iOS - Referencia de configuración

Este documento proporciona una referencia completa de todas las opciones de configuración disponibles en el SDK de Singular para aplicaciones iOS. El objeto SingularConfig permite personalizar el comportamiento del SDK, incluidos los ajustes de seguimiento, las opciones de atribución, los controles de privacidad y mucho más. Cada propiedad de configuración se presenta con una descripción, firma y ejemplos prácticos de uso.

appGroupName

Propiedad SingularConfig.appGroupName

Establece el nombre del grupo de aplicaciones para compartir datos entre la aplicación principal y las extensiones de aplicaciones. Esto es necesario cuando se utilizan extensiones de aplicaciones con el SDK.

Firma

@property (strong) NSString *appGroupName;

Ejemplo de uso

// Set app group name for app extensions
config.appGroupName = "group.com.yourcompany.yourapp"

// Set app group name for app extensions
config.appGroupName = @"group.com.yourcompany.yourapp";

clipboardAttribution

Función de empresa: El DDL basado en portapapeles requiere Singular WebSDK, que es una función para empresas. Póngase en contacto con su Customer Success Manager para activar esta función en su cuenta.

Propiedad SingularConfig.clipboardAttribution

Habilita la atribución de portapapeles para el SDK. Si está activada, el SDK comprobará el portapapeles del dispositivo en busca de enlaces de atribución durante la inicialización.

Firma

@property (assign) BOOL clipboardAttribution;

Ejemplo de uso

// Enable clipboard attribution
config.clipboardAttribution = true

// Enable clipboard attribution
config.clipboardAttribution = YES;

conversionValueUpdatedCallback

Propiedad conversionValueUpdatedCallback de SingularConfig

Establece una función de devolución de llamada a la que se llamará cuando se actualice el valor de conversión de SKAdNetwork. Esto le permite reaccionar ante cambios en el valor de conversión.

Firma

@property (copy) void(^conversionValueUpdatedCallback)(NSInteger);

Ejemplo de uso

// Set conversion value updated callback
config.conversionValueUpdatedCallback = { conversionValue in
    print("Conversion value updated to: \(conversionValue)")
    // Update UI or take other actions based on the new conversion value
}

// Set conversion value updated callback
config.conversionValueUpdatedCallback = ^(NSInteger conversionValue) {
    NSLog(@"Conversion value updated to: %ld", (long)conversionValue);
    // Update UI or take other actions based on the new conversion value
};

conversionValuesUpdatedCallback

Propiedad conversionValuesUpdatedCallback de SingularConfig

Establece una función de devolución de llamada a la que se llamará cuando se actualicen los valores de conversión de SKAdNetwork 4.0. Esto es específico de iOS 16.1+ y permite reaccionar ante cambios en los valores finos, gruesos y de bloqueo.

Firma

@property (copy) void(^conversionValuesUpdatedCallback)(NSNumber *, NSNumber *, BOOL);

Ejemplo de uso

// Set conversion values updated callback for SKAdNetwork 4.0
config.conversionValuesUpdatedCallback = { fineValue, coarseValue, lock in
    print("Conversion values updated - Fine: \(fineValue ?? 0), Coarse: \(coarseValue ?? 0), Lock: \(lock)")
    // Update UI or take other actions based on the new conversion values
}

// Set conversion values updated callback for SKAdNetwork 4.0
config.conversionValuesUpdatedCallback = ^(NSNumber *fineValue, NSNumber *coarseValue, BOOL lock) {
    NSLog(@"Conversion values updated - Fine: %@, Coarse: %@, Lock: %d", 
          fineValue, coarseValue, lock);
    // Update UI or take other actions based on the new conversion values
};

customSdid

Propiedad singularConfig.customSdid

Característica de empresa: Establece un SDID (identificador de dispositivo de Singular) personalizado. Esto le permite proporcionar su propio identificador de dispositivo en lugar de utilizar el generado por Singular.

Firma

@property (strong) NSString *customSdid;

Ejemplo de uso

// Set custom SDID
config.customSdid = "custom-device-id-12345"

// Set custom SDID
config.customSdid = @"custom-device-id-12345";

deviceAttributionCallback

Propiedad deviceAttributionCallback de SingularConfig

Característica BETA: Establece una función de devolución de llamada que se llamará cuando estén disponibles los datos de atribución del dispositivo. Esto permite acceder a los datos de atribución en cuanto están disponibles.

Firma

@property (copy) void(^deviceAttributionCallback)(NSDictionary *);

Ejemplo de uso

// Set device attribution callback
config.deviceAttributionCallback = { attributionData in
    print("Attribution data received: \(attributionData)")

    // Access specific attribution parameters
    let campaign = attributionData["campaign"] as? String
    let source = attributionData["source"] as? String
    let adSet = attributionData["adSet"] as? String

    // Update UI or take actions based on attribution data
    if let campaign = campaign {
        self.showCampaignSpecificContent(campaign)
    }
}

// Set device attribution callback
config.deviceAttributionCallback = ^(NSDictionary *attributionData) {
    NSLog(@"Attribution data received: %@", attributionData);

    // Access specific attribution parameters
    NSString *campaign = attributionData[@"campaign"];
    NSString *source = attributionData[@"source"];
    NSString *adSet = attributionData[@"adSet"];

    // Update UI or take actions based on attribution data
    if (campaign) {
        [self showCampaignSpecificContent:campaign];
    }
};

didSetSdidHandler

Propiedad didSetSdidHandler de SingularConfig

Característica de empresa: Establece una función de callback que se llamará cuando se establezca el SDID (Singular Device ID). Esto le permite recibir una notificación cuando el SDID personalizado se ha establecido correctamente.

Firma

typedef void (^SdidAccessorHandler)(NSString *result);
@property (copy) SdidAccessorHandler didSetSdidHandler;

Ejemplo de uso

// Set callback for when SDID is set
config.customSdid = "custom-device-id-12345"
config.didSetSdidHandler = { sdid in
    print("SDID was set: \(sdid)")
    // Perform any actions needed after SDID is set
}

// Set callback for when SDID is set
config.customSdid = @"custom-device-id-12345";
config.didSetSdidHandler = ^(NSString *sdid) {
    NSLog(@"SDID was set: %@", sdid);
    // Perform any actions needed after SDID is set
};

enableOdmWithTimeoutInterval

Propiedad enableOdmWithTimeoutInterval de SingularConfig

Establece el intervalo de tiempo de espera en segundos para la recuperación de Google ODM (Organic Data Measurement). Esta función se utiliza para recuperar datos de instalación orgánicos de Google Play.

Firma

@property (assign) NSInteger enableOdmWithTimeoutInterval;

Ejemplo de uso

// Enable Google ODM with 5 second timeout
config.enableOdmWithTimeoutInterval = 5

// Enable Google ODM with 5 second timeout
config.enableOdmWithTimeoutInterval = 5;

espDominios

Propiedad SingularConfig.espDomains

Establece los dominios ESP (proveedor de servicios de correo electrónico) para la atribución de correo electrónico. Permite especificar qué dominios de correo electrónico deben tenerse en cuenta para la atribución.

Firma

@property (strong) NSArray *espDomains;

Ejemplo de uso

// Set ESP domains for email attribution
config.espDomains = ["mailchimp.com", "sendgrid.net", "campaign-monitor.com"]

// Set ESP domains for email attribution
config.espDomains = @[@"mailchimp.com", @"sendgrid.net", @"campaign-monitor.com"];

globalProperties

Propiedad globalProperties de SingularConfig

Proporciona acceso de sólo lectura al diccionario de propiedades globales. Contiene todas las propiedades globales que se han establecido para la configuración.

Firma

@property (readonly) NSMutableDictionary *globalProperties;

Ejemplo de uso

// Access global properties
print("Global properties: \(config.globalProperties)")

// Access global properties
NSLog(@"Global properties: %@", config.globalProperties);

initWithApiKey

Inicialización de SingularConfig

Inicializa un nuevo objeto SingularConfig con su clave y secreto de API. Este es el primer paso para configurar Singular SDK.

Firma

- (id)initWithApiKey:(NSString *)apikey andSecret:(NSString *)secret;

Ejemplo de uso

// Create configuration object
let config = SingularConfig(apiKey: "SDK KEY", andSecret: "YOUR_SECRET")

// Create configuration object
SingularConfig *config = [[SingularConfig alloc] initWithApiKey:@"SDK KEY" 
                                                       andSecret:@"YOUR_SECRET"];

launchOptions

Propiedad SingularConfig.launchOptions

Establece el diccionario de opciones de lanzamiento del delegado de la aplicación. Se utiliza para procesar enlaces profundos y otros datos de lanzamiento.

Firma

@property (strong) NSDictionary *launchOptions;

Ejemplo de uso

// Set launch options from app delegate
func application(_ application: UIApplication, 
                 didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    let config = SingularConfig(apiKey: "API_KEY", andSecret: "SECRET")
    config.launchOptions = launchOptions
    Singular.start(config)
    return true
}

// Set launch options from app delegate
- (BOOL)application:(UIApplication *)application 
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    SingularConfig *config = [[SingularConfig alloc] initWithApiKey:@"API_KEY" 
                                                           andSecret:@"SECRET"];
    config.launchOptions = launchOptions;
    [Singular start:config];
    return YES;
}

limitAdvertisingIdentifiers

Propiedad limitAdvertisingIdentifiers de SingularConfig

Activa o desactiva el uso de identificadores de publicidad. Esta opción afecta al modo en que el SDK recopila y utiliza los identificadores de dispositivo para el seguimiento y la atribución.

Firma

@property (assign) BOOL limitAdvertisingIdentifiers;

Ejemplo de uso

// Enable limited identifiers mode
config.limitAdvertisingIdentifiers = true

// Enable limited identifiers mode
config.limitAdvertisingIdentifiers = YES;

manualSkanConversionManagement

Propiedad SingularConfig.manualSkanConversionManagement

Habilita la gestión manual de los valores de conversión de SKAdNetwork. Cuando está activada, el SDK no actualizará automáticamente los valores de conversión, permitiéndole controlarlos manualmente.

Firma

@property (assign) BOOL manualSkanConversionManagement;

Ejemplo de uso

// Enable manual SKAdNetwork conversion management
config.manualSkanConversionManagement = true

// Enable manual SKAdNetwork conversion management
config.manualSkanConversionManagement = YES;

openUrl

Propiedad singularConfig.openUrl

Establece la URL utilizada para abrir la aplicación. Se utiliza para los enlaces profundos de esquemas de URL personalizados.

Firma

@property (strong) NSURL *openUrl;

Ejemplo de uso

// Set open URL for custom URL schemes
func application(_ app: UIApplication, 
                 open url: URL, 
                 options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
    let config = SingularConfig(apiKey: "API_KEY", andSecret: "SECRET")
    config.openUrl = url
    Singular.start(config)
    return true
}

// Set open URL for custom URL schemes
- (BOOL)application:(UIApplication *)app 
            openURL:(NSURL *)url 
            options:(NSDictionary *)options {
    SingularConfig *config = [[SingularConfig alloc] initWithApiKey:@"API_KEY" 
                                                           andSecret:@"SECRET"];
    config.openUrl = url;
    [Singular start:config];
    return YES;
}

pushNotificationLinkPath

Propiedad pushNotificationLinkPath de SingularConfig

Establece las rutas para buscar enlaces profundos en las cargas útiles de las notificaciones push. Esto ayuda al SDK a encontrar y procesar enlaces de atribución en las notificaciones push.

Firma

@property (strong) NSArray<NSArray<NSString*>*> *pushNotificationLinkPath;

Ejemplo de uso

// Set push notification link paths
config.pushNotificationLinkPath = [
    ["data", "deeplink"],
    ["notification", "data", "url"],
    ["custom", "link"]
]

// Set push notification link paths
config.pushNotificationLinkPath = @[
    @[@"data", @"deeplink"],
    @[@"notification", @"data", @"url"],
    @[@"custom", @"link"]
];

pushNotificationPayload

Propiedad pushNotificationPayload de SingularConfig

Establece la carga útil de la notificación push para la atribución. Esto permite al SDK procesar los datos de notificación push durante la inicialización.

Firma

@property (strong) NSDictionary *pushNotificationPayload;

Ejemplo de uso

// Set push notification payload
config.pushNotificationPayload = userInfo

// Set push notification payload
config.pushNotificationPayload = userInfo;

sdidReceivedHandler

Propiedad SingularConfig.sdidReceivedHandler

Característica empresarial: Establece una función callback que se llamará cuando se reciba el SDID (Singular Device ID). Esto le permite acceder al SDID tan pronto como esté disponible.

Firma

typedef void (^SdidAccessorHandler)(NSString *result);
@property (copy) SdidAccessorHandler sdidReceivedHandler;

Ejemplo de uso

// Set callback for when SDID is received
config.sdidReceivedHandler = { sdid in
    print("SDID received: \(sdid)")
    // Store or use the SDID as needed
    self.storeDeviceIdentifier(sdid)
}

// Set callback for when SDID is received
config.sdidReceivedHandler = ^(NSString *sdid) {
    NSLog(@"SDID received: %@", sdid);
    // Store or use the SDID as needed
    [self storeDeviceIdentifier:sdid];
};

setGlobalProperty

SingularConfig.setGlobalProperty Método

Establece una propiedad global durante la inicialización del SDK. Esta propiedad se enviará con todos los eventos rastreados por el SDK. Se trata de un método en lugar de una propiedad, lo que permite una configuración encadenada.

Firma

- (void)setGlobalProperty:(NSString *)key 
                withValue:(NSString *)value 
         overrideExisting:(BOOL)overrideExisiting;

Ejemplo de uso

// Add global properties
config.setGlobalProperty("app_version", 
                         withValue: "1.2.3", 
                         overrideExisting: true)

config.setGlobalProperty("user_type", 
                         withValue: "free", 
                         overrideExisting: true)

// Add global properties
[config setGlobalProperty:@"app_version" 
                withValue:@"1.2.3" 
         overrideExisting:YES];

[config setGlobalProperty:@"user_type" 
                withValue:@"free" 
         overrideExisting:YES];

shortLinkResolveTimeOut

Propiedad SingularConfig.shortLinkResolveTimeOut

Establece el tiempo de espera en segundos para la resolución de enlaces cortos. Determina cuánto tiempo esperará el SDK a que se resuelva un enlace corto antes de continuar con la inicialización. El valor predeterminado es 10 segundos.

Firma

@property (assign) long shortLinkResolveTimeOut;

Ejemplo de uso

// Set short link resolve timeout to 15 seconds
config.shortLinkResolveTimeOut = 15

// Set short link resolve timeout to 15 seconds
config.shortLinkResolveTimeOut = 15;

singularLinksHandler

Propiedad singularConfig.singularLinksHandler

Establece una función de devolución de llamada para gestionar los enlaces profundos procesados por Singular. Esto permite que su aplicación responda a los enlaces profundos utilizados en la atribución.

Firma

@property (copy) void(^singularLinksHandler)(SingularLinkParams *);

Ejemplo de uso

// Set singular links handler
config.singularLinksHandler = { params in
    // Check if we have a deep link
    if let deeplink = params.deeplink {
        print("Deep link received: \(deeplink)")

        // Navigate based on the deep link
        self.navigateToScreen(deeplink)
    }

    // Check if this is a deferred deep link
    if params.isDeferred {
        print("This is a deferred deep link")
    }

    // Access passthrough parameters
    if let passthrough = params.passthrough {
        print("Passthrough data: \(passthrough)")
    }
}

// Set singular links handler
config.singularLinksHandler = ^(SingularLinkParams *params) {
    // Check if we have a deep link
    if (params.deeplink) {
        NSLog(@"Deep link received: %@", params.deeplink);

        // Navigate based on the deep link
        [self navigateToScreen:params.deeplink];
    }

    // Check if this is a deferred deep link
    if (params.isDeferred) {
        NSLog(@"This is a deferred deep link");
    }

    // Access passthrough parameters
    if (params.passthrough) {
        NSLog(@"Passthrough data: %@", params.passthrough);
    }
};

skAdNetworkEnabled

Propiedad SingularConfig.skAdNetworkEnabled

Activa o desactiva la compatibilidad con SKAdNetwork. Controla si el SDK utilizará SKAdNetwork de Apple para la atribución. El valor por defecto es YES.

Firma

@property (assign) BOOL skAdNetworkEnabled;

Ejemplo de uso

// Disable SKAdNetwork support if needed
config.skAdNetworkEnabled = false

// Disable SKAdNetwork support if needed
config.skAdNetworkEnabled = NO;

supportAppExtension

Propiedad singularConfig.supportAppExtension

Habilita la compatibilidad con extensiones de aplicaciones. Cuando está activada, el SDK puede funcionar correctamente en contextos de extensión de aplicaciones.

Firma

@property (assign) BOOL supportAppExtension;

Ejemplo de uso

// Enable app extension support
config.supportAppExtension = true

// Enable app extension support
config.supportAppExtension = YES;

userActivity

Propiedad singularConfig.userActivity

Establece el objeto de actividad del usuario para manejar enlaces universales. Se utiliza cuando la aplicación se abre a través de un enlace universal.

Firma

@property (strong) NSUserActivity *userActivity;

Ejemplo de uso

// Set user activity for universal links
func application(_ application: UIApplication, 
                 continue userActivity: NSUserActivity, 
                 restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
    let config = SingularConfig(apiKey: "API_KEY", andSecret: "SECRET")
    config.userActivity = userActivity
    Singular.start(config)
    return true
}

// Set user activity for universal links
- (BOOL)application:(UIApplication *)application 
continueUserActivity:(NSUserActivity *)userActivity 
  restorationHandler:(void (^)(NSArray *))restorationHandler {
    SingularConfig *config = [[SingularConfig alloc] initWithApiKey:@"API_KEY" 
                                                           andSecret:@"SECRET"];
    config.userActivity = userActivity;
    [Singular start:config];
    return YES;
}

waitForTrackingAuthorizationWithTimeoutInterval

SingularConfig.waitForTrackingAuthorizationWithTimeoutInterval Propiedad

Establece el intervalo de tiempo de espera en segundos para la respuesta de autorización de seguimiento del usuario en iOS 14+. Determina cuánto tiempo esperará el SDK a la respuesta de solicitud de ATT antes de continuar con la inicialización.

Firma

@property (assign) NSInteger waitForTrackingAuthorizationWithTimeoutInterval;

Ejemplo de uso

// Wait up to 60 seconds for ATT prompt response
config.waitForTrackingAuthorizationWithTimeoutInterval = 60

// Wait up to 60 seconds for ATT prompt response
config.waitForTrackingAuthorizationWithTimeoutInterval = 60;

Ejemplo de configuración completa

Configuración completa del SDK

El siguiente ejemplo muestra cómo crear una configuración completa estableciendo varias propiedades de configuración juntas.

Ejemplo completo

// Create configuration with API credentials
let config = SingularConfig(apiKey: "SDK KEY", andSecret: "YOUR_SECRET")

// Set basic options
config.waitForTrackingAuthorizationWithTimeoutInterval = 60
config.clipboardAttribution = true

// Set global properties
config.setGlobalProperty("app_version", 
                         withValue: "1.2.3", 
                         overrideExisting: true)
config.setGlobalProperty("user_type", 
                         withValue: "premium", 
                         overrideExisting: true)

// Configure SKAdNetwork
config.skAdNetworkEnabled = true
config.manualSkanConversionManagement = false
config.conversionValueUpdatedCallback = { conversionValue in
    print("Conversion value updated: \(conversionValue)")
}

// Configure deep links
config.launchOptions = launchOptions
config.singularLinksHandler = { params in
    if let deeplink = params.deeplink {
        print("Deep link received: \(deeplink)")
        self.handleDeepLink(deeplink)
    }
}

// Configure attribution callback
config.deviceAttributionCallback = { attributionData in
    print("Attribution data: \(attributionData)")
}

// Start the SDK
Singular.start(config)

// Create configuration with API credentials
SingularConfig *config = [[SingularConfig alloc] initWithApiKey:@"SDK KEY" 
                                                       andSecret:@"YOUR_SECRET"];

// Set basic options
config.waitForTrackingAuthorizationWithTimeoutInterval = 60;
config.clipboardAttribution = YES;

// Set global properties
[config setGlobalProperty:@"app_version" 
                withValue:@"1.2.3" 
         overrideExisting:YES];
[config setGlobalProperty:@"user_type" 
                withValue:@"premium" 
         overrideExisting:YES];

// Configure deep links
config.launchOptions = launchOptions;
config.singularLinksHandler = ^(SingularLinkParams *params) {
    if (params.deeplink) {
        NSLog(@"Deep link received: %@", params.deeplink);
        [self handleDeepLink:params.deeplink];
    }
};

// Start the SDK
[Singular start:config];

SDK de iOS - Referencia de métodos de configuración

SDK iOS - Referencia de configuración

appGroupName

Propiedad SingularConfig.appGroupName

Firma

Ejemplo de uso

clipboardAttribution

Propiedad SingularConfig.clipboardAttribution

Firma

Ejemplo de uso

conversionValueUpdatedCallback

Propiedad conversionValueUpdatedCallback de SingularConfig

Firma

Ejemplo de uso

conversionValuesUpdatedCallback

Propiedad conversionValuesUpdatedCallback de SingularConfig

Firma

Ejemplo de uso

customSdid

Propiedad singularConfig.customSdid

Firma

Ejemplo de uso

deviceAttributionCallback

Propiedad deviceAttributionCallback de SingularConfig

Firma

Ejemplo de uso

didSetSdidHandler

Propiedad didSetSdidHandler de SingularConfig

Firma

Ejemplo de uso

enableOdmWithTimeoutInterval

Propiedad enableOdmWithTimeoutInterval de SingularConfig

Firma

Ejemplo de uso

espDominios

Propiedad SingularConfig.espDomains

Firma

Ejemplo de uso

globalProperties

Propiedad globalProperties de SingularConfig

Firma

Ejemplo de uso

initWithApiKey

Inicialización de SingularConfig

Firma

Ejemplo de uso

launchOptions

Propiedad SingularConfig.launchOptions

Firma

Ejemplo de uso

limitAdvertisingIdentifiers

Propiedad limitAdvertisingIdentifiers de SingularConfig

Firma

Ejemplo de uso

manualSkanConversionManagement

Propiedad SingularConfig.manualSkanConversionManagement

Firma

Ejemplo de uso

openUrl

Propiedad singularConfig.openUrl

Firma

Ejemplo de uso

pushNotificationLinkPath

Propiedad pushNotificationLinkPath de SingularConfig

Firma

Ejemplo de uso

pushNotificationPayload

Propiedad pushNotificationPayload de SingularConfig

Firma

Ejemplo de uso

sdidReceivedHandler

Propiedad SingularConfig.sdidReceivedHandler

Firma

Ejemplo de uso

setGlobalProperty

SingularConfig.setGlobalProperty Método

Firma

Ejemplo de uso

shortLinkResolveTimeOut

Propiedad SingularConfig.shortLinkResolveTimeOut