Documento

SDK do iOS - Referência de Configuração

Este documento fornece uma referência abrangente para todas as opções de configuração disponíveis no Singular SDK para aplicativos iOS. O objeto SingularConfig permite-lhe personalizar o comportamento do SDK, incluindo definições de rastreio, opções de atribuição, controlos de privacidade e muito mais. Cada propriedade de configuração é apresentada com uma descrição, assinatura e exemplos práticos de uso.

appGroupName

Propriedade SingularConfig.appGroupName

Define o nome do grupo de aplicativos para compartilhar dados entre o aplicativo principal e as extensões de aplicativos. Isso é necessário ao usar extensões de aplicativos com o SDK.

Assinatura

@property (strong) NSString *appGroupName;

Exemplo de utilização

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

Funcionalidade empresarial: A DDL baseada em prancheta requer o Singular WebSDK, que é um recurso corporativo. Contacte o seu Gestor de Sucesso do Cliente para ativar esta funcionalidade para a sua conta.

Propriedade SingularConfig.clipboardAttribution

Habilita a atribuição da área de transferência para o SDK. Quando ativada, o SDK verificará a área de transferência do dispositivo em busca de links de atribuição durante a inicialização.

Assinatura

@property (assign) BOOL clipboardAttribution;

Exemplo de utilização

// Enable clipboard attribution
config.clipboardAttribution = true

// Enable clipboard attribution
config.clipboardAttribution = YES;

conversionValueUpdatedCallback

Propriedade SingularConfig.conversionValueUpdatedCallback

Define uma função de retorno de chamada a ser chamada quando o valor de conversão SKAdNetwork é atualizado. Isto permite-lhe reagir às alterações do valor de conversão.

Assinatura

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

Exemplo de utilização

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

Propriedade SingularConfig.conversionValuesUpdatedCallback

Define uma função de retorno de chamada a ser chamada quando os valores de conversão da SKAdNetwork 4.0 são actualizados. Isto é específico do iOS 16.1+ e permite-lhe reagir a alterações nos valores finos, grossos e de bloqueio.

Assinatura

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

Exemplo de utilização

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

Propriedade SingularConfig.customSdid

Caraterística da empresa: Define um SDID (Singular Device ID) personalizado. Isso permite que o usuário forneça seu próprio identificador de dispositivo em vez de usar o gerado pelo Singular.

Assinatura

@property (strong) NSString *customSdid;

Exemplo de uso

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

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

deviceAttributionCallback

Propriedade SingularConfig.deviceAttributionCallback

Caraterística BETA: Define uma função de retorno de chamada a ser chamada quando os dados de atribuição do dispositivo estiverem disponíveis. Isto permite-lhe aceder aos dados de atribuição assim que estiverem disponíveis.

Assinatura

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

Exemplo de utilização

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

Propriedade SingularConfig.didSetSdidHandler

Caraterística da empresa: Define uma função de retorno de chamada a ser chamada quando o SDID (Singular Device ID) é definido. Isto permite-lhe ser notificado quando o SDID personalizado tiver sido definido com êxito.

Assinatura

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

Exemplo de utilização

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

Propriedade SingularConfig.enableOdmWithTimeoutInterval

Define o intervalo de tempo limite em segundos para a recuperação do Google ODM (Organic Data Measurement). Este recurso é usado para recuperar dados de instalação orgânica do Google Play.

Assinatura

@property (assign) NSInteger enableOdmWithTimeoutInterval;

Exemplo de utilização

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

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

espDomínios

Propriedade SingularConfig.espDomains

Define os domínios ESP (Fornecedor de serviços de e-mail) para atribuição de e-mail. Isto permite-lhe especificar quais os domínios de correio eletrónico que devem ser considerados para atribuição.

Assinatura

@property (strong) NSArray *espDomains;

Exemplo de utilização

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

Propriedade SingularConfig.globalProperties

Fornece acesso só de leitura ao dicionário de propriedades globais. Este contém todas as propriedades globais que foram definidas para a configuração.

Assinatura

@property (readonly) NSMutableDictionary *globalProperties;

Exemplo de uso

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

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

initWithApiKey

Inicialização de SingularConfig

Inicializa um novo objeto SingularConfig com sua chave de API e segredo. Este é o primeiro passo na configuração do Singular SDK.

Assinatura

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

Exemplo 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

Propriedade SingularConfig.launchOptions

Define o dicionário de opções de inicialização do delegado do aplicativo. Este é utilizado para processar ligações diretas e outros dados de lançamento.

Assinatura

@property (strong) NSDictionary *launchOptions;

Exemplo de utilização

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

Propriedade SingularConfig.limitAdvertisingIdentifiers

Ativa ou desactiva a utilização de identificadores de publicidade. Esta opção afecta a forma como o SDK recolhe e utiliza identificadores de dispositivos para rastreio e atribuição.

Assinatura

@property (assign) BOOL limitAdvertisingIdentifiers;

Exemplo de utilização

// Enable limited identifiers mode
config.limitAdvertisingIdentifiers = true

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

manualSkanConversionManagement

Propriedade SingularConfig.manualSkanConversionManagement

Permite a gestão manual dos valores de conversão da SKAdNetwork. Quando activada, o SDK não actualizará automaticamente os valores de conversão, permitindo-lhe controlá-los manualmente.

Assinatura

@property (assign) BOOL manualSkanConversionManagement;

Exemplo de utilização

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

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

openUrl

Propriedade SingularConfig.openUrl

Define o URL utilizado para abrir a aplicação. Isto é utilizado para ligações diretas de esquemas URL personalizados.

Assinatura

@property (strong) NSURL *openUrl;

Exemplo 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

Propriedade SingularConfig.pushNotificationLinkPath

Define os caminhos para procurar links diretos em cargas de notificação push. Isso ajuda o SDK a encontrar e processar links de atribuição em notificações push.

Assinatura

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

Exemplo 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

Propriedade SingularConfig.pushNotificationPayload

Define a carga útil da notificação push para atribuição. Isso permite que o SDK processe os dados da notificação push durante a inicialização.

Assinatura

@property (strong) NSDictionary *pushNotificationPayload;

Exemplo de uso

// Set push notification payload
config.pushNotificationPayload = userInfo

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

sdidReceivedHandler

Propriedade SingularConfig.sdidReceivedHandler

Funcionalidade empresarial: Define uma função de retorno de chamada a ser chamada quando o SDID (Singular Device ID) é recebido. Isto permite-lhe aceder ao SDID logo que este esteja disponível.

Assinatura

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

Exemplo de utilização

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

Método SingularConfig.setGlobalProperty

Define uma propriedade global durante a inicialização do SDK. Essa propriedade será enviada com todos os eventos rastreados pelo SDK. Este é um método em vez de uma propriedade, permitindo a configuração encadeada.

Assinatura

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

Exemplo de utilização

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

SingularConfig.shortLinkResolveTimeOut Propriedade

Define o tempo limite em segundos para a resolução de links curtos. Isso determina quanto tempo o SDK aguardará a resolução de um link curto antes de continuar com a inicialização. O valor padrão é 10 segundos.

Assinatura

@property (assign) long shortLinkResolveTimeOut;

Exemplo 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

SingularConfig.singularLinksHandler Propriedade

Define uma função de retorno de chamada para lidar com deep links processados pelo Singular. Isso permite que seu aplicativo responda a deep links usados na atribuição.

Assinatura

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

Exemplo 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

Propriedade SingularConfig.skAdNetworkEnabled

Ativa ou desactiva o suporte de SKAdNetwork. Isto controla se o SDK irá utilizar a SKAdNetwork da Apple para atribuição. O valor predefinido é YES.

Assinatura

@property (assign) BOOL skAdNetworkEnabled;

Exemplo de utilização

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

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

supportAppExtension

Propriedade SingularConfig.supportAppExtension

Ativa o suporte para extensões de aplicações. Quando ativado, o SDK pode funcionar corretamente em contextos de extensão de aplicações.

Assinatura

@property (assign) BOOL supportAppExtension;

Exemplo de uso

// Enable app extension support
config.supportAppExtension = true

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

userActivity

SingularConfig.userActivity Propriedade

Define o objeto de atividade do utilizador para lidar com ligações universais. Este é utilizado quando a aplicação é aberta através de uma ligação universal.

Assinatura

@property (strong) NSUserActivity *userActivity;

Exemplo 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

Propriedade SingularConfig.waitForTrackingAuthorizationWithTimeoutInterval

Define o intervalo de tempo limite em segundos para aguardar a resposta de autorização de rastreamento do usuário no iOS 14+. Isso determina quanto tempo o SDK aguardará a resposta do prompt ATT antes de continuar com a inicialização.

Assinatura

@property (assign) NSInteger waitForTrackingAuthorizationWithTimeoutInterval;

Exemplo 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;

Exemplo de configuração completa

Configuração abrangente do SDK

O exemplo a seguir demonstra como criar uma configuração abrangente definindo várias propriedades de configuração juntas.

Exemplo 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 do iOS - Referência dos métodos de configuração

SDK do iOS - Referência de Configuração

appGroupName

Propriedade SingularConfig.appGroupName

Assinatura

Exemplo de utilização

clipboardAttribution

Propriedade SingularConfig.clipboardAttribution

Assinatura

Exemplo de utilização

conversionValueUpdatedCallback

Propriedade SingularConfig.conversionValueUpdatedCallback

Assinatura

Exemplo de utilização

conversionValuesUpdatedCallback

Propriedade SingularConfig.conversionValuesUpdatedCallback

Assinatura

Exemplo de utilização

customSdid

Propriedade SingularConfig.customSdid

Assinatura

Exemplo de uso

deviceAttributionCallback

Propriedade SingularConfig.deviceAttributionCallback

Assinatura

Exemplo de utilização

didSetSdidHandler

Propriedade SingularConfig.didSetSdidHandler

Assinatura

Exemplo de utilização

enableOdmWithTimeoutInterval

Propriedade SingularConfig.enableOdmWithTimeoutInterval

Assinatura

Exemplo de utilização

espDomínios

Propriedade SingularConfig.espDomains

Assinatura

Exemplo de utilização

globalProperties

Propriedade SingularConfig.globalProperties

Assinatura

Exemplo de uso

initWithApiKey

Inicialização de SingularConfig

Assinatura

Exemplo de uso

launchOptions

Propriedade SingularConfig.launchOptions

Assinatura

Exemplo de utilização

limitAdvertisingIdentifiers

Propriedade SingularConfig.limitAdvertisingIdentifiers

Assinatura

Exemplo de utilização

manualSkanConversionManagement

Propriedade SingularConfig.manualSkanConversionManagement

Assinatura

Exemplo de utilização

openUrl

Propriedade SingularConfig.openUrl

Assinatura

Exemplo de uso

pushNotificationLinkPath

Propriedade SingularConfig.pushNotificationLinkPath

Assinatura

Exemplo de uso

pushNotificationPayload

Propriedade SingularConfig.pushNotificationPayload

Assinatura

Exemplo de uso

sdidReceivedHandler

Propriedade SingularConfig.sdidReceivedHandler

Assinatura

Exemplo de utilização

setGlobalProperty

Método SingularConfig.setGlobalProperty

Assinatura

Exemplo de utilização

shortLinkResolveTimeOut

SingularConfig.shortLinkResolveTimeOut Propriedade