1. Baixe e instale a versão mais recente do CocoaPods.

2. Para criar um podfile, navegue até a pasta raiz do projeto no Terminal e digite:

   pod init

3. Para adicionar a dependência do Singular SDK, adicione o seguinte ao Podfile do seu projeto:

   pod 'Singular-SDK'

   Por exemplo:

   

4. No Terminal, navegue até a pasta raiz do projeto e execute:

   pod install

5. Deste ponto em diante, abra o arquivo de espaço de trabalho do Xcode .xcworkspace para abrir o projeto, em vez do arquivo .xcodeproj.
6. Crie um cabeçalho de ponte Swift de acordo com as instruções abaixo.

1. No Xcode, vá para Arquivo > Adicionar pacotes e insira o repositório Singular SDK do GitHub:

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

   

2. Atualize a versão do Singular SDK:

   

3. Clique no botão Adicionar pacote.

4. Vá para Fases de construção > Vincular binário com bibliotecas e adicione a biblioteca AdServices.framework. Certifique-se de que a marca como Opcional, uma vez que só está disponível para dispositivos com iOS 14.3 e superior.

   

5. Vá para Configurações de compilação > Vinculação > Outros sinalizadores de vinculador e atualize Outros sinalizadores de vinculador com os seguintes itens:
   
   $(inherited) -ObjC -l "sqlite3.0" -l "z" -framework "AdSupport" -framework "Security" -framework "Singular" -framework "StoreKit" -framework "SystemConfiguration" -framework "WebKit" -framework "iAd"

   

   

6. Crie um cabeçalho de ponte Swift de acordo com as instruções abaixo.

Está a atualizar a partir do Singular SDK 12.3.2 ou inferior?

Siga as etapas abaixo para remover a Biblioteca estática antiga

1. Navegue até os arquivos do projeto e remova a biblioteca estática Singular. Normalmente, deve haver uma pasta com o nome Singular-iOS-sdk-v12.3.2. Clique com o botão direito do mouse na pasta e exclua-a do projeto.
2. Prossiga para a próxima secção para instalar a nova estrutura

Adicionando o Singular Framework pela primeira vez

1. Descarregue e descompacte a Estrutura SDK.

   Selecione o Framework correto para sua implementação:

   • Para o Xcode 12 e superior, use o .xcframework [BAIXE AQUI]
   • Para o Xcode 11 e inferior, use o .framework [BAIXE AQUI]

2. Adicione a pasta descompactada a uma pasta no seu projeto do Xcode:

   No Xcode, clique com o botão direito do mouse em Nome do seu aplicativo > Adicionar arquivos a [Nome do seu projeto]. Na caixa de diálogo que se abre, selecione Opções > Criar grupos e adicione a pasta onde descompactou o SDK.
   
   
   
   
   
   O framework Singular agora deve estar no seu projeto
   
   

3. Para adicionar as bibliotecas necessárias:

   • No Xcode, selecione Fases de construção > Ligar o binário às bibliotecas.

   • Clique em + e adicione as seguintes bibliotecas:

     Libsqlite3.0.tbd
     SystemConfiguration.framework
     Security.framework
     Libz.tbd
     AdSupport.framework
     WebKit.framework
     StoreKit.framework
     AdServices.framework (mark as Optional since it's only
         available for devices with iOS 14.3 and higher).

4. Incorporar e assinar a estrutura Singular
   • Navegue até Geral > Estruturas, bibliotecas e conteúdo incorporado
   • Ajuste a Estrutura Singular para ser"Incorporar e assinar"
     
     

Se você instalou o SDK usando CocoaPods ou o Gerenciador de Pacotes Swift, é necessário criar um Cabeçalho de Ponte para que o Swift use as bibliotecas Obj-C do SDK Singular.

1. No seu projeto, crie um novo arquivo do tipo Header e nomeie-o YourProjectName-Bridging-Header.

   

2. Abra o arquivo e adicione o seguinte:

   #import <Singular/Singular.h>

   Por exemplo:

   

3. Vá para Configurações de construção > Cabeçalho de ponte Objective-C e adicione o caminho relativo do arquivo:

   

Se pretender atualizar o valor de conversão por si próprio utilizando o código da aplicação, tem primeiro de definir o sinalizador manualSkanConversionManagement na Singular Config. Isto permite-lhe utilizar vários métodos SDK para obter e atualizar o valor de conversão manualmente.

Para ativar o Modo Manual:

func getConfig() -> SingularConfig? {
     
     // Singular Config Options


     guard let config = SingularConfig(apiKey: Constants.APIKEY,
       andSecret: Constants.SECRET) else {
         return nil
         }
     
     //...
     config.manualSkanConversionManagement = true
     //...
     
     return config
}

- (SingularConfig *)getConfig {
     
     // Singular Config Options


     SingularConfig* config = [[SingularConfig alloc] initWithApiKey:APIKEY
       andSecret:SECRET];
     
     //...
     config.manualSkanConversionManagement = YES;
     //...
     
     return config;
}

Para atualizar o valor de conversão:

No Modo Manual, para atualizar o valor de conversão, é necessário utilizar o método skanUpdateConversionValue. Pode utilizá-lo sempre que necessário no ciclo de vida da sua aplicação.

// Sending a Standard Event for Login


Singular.event(EVENT_SNG_LOGIN)
      
// Manually updating the conversion value to 7 after the Event


Singular.skanUpdateConversionValue(7)

// Sending a Standard Event for Login


[Singular event:EVENT_SNG_LOGIN];
      
// Manually updating the conversion value to 7 after the Event


[Singular skanUpdateConversionValue:7];

Outros métodos SKAdNetwork:

Para obter o valor de conversão atual, utilize o método skanGetConversionValue ou conversionValueUpdatedCallback. Ambos funcionam em Managed Mode e Manual Mode.

let conversionValue = Singular.skanGetConversionValue()

NSNumber* conversionValue = [Singular skanGetConversionValue]; 

func getConfig() -> SingularConfig? {
     // Singular Config Options


     guard let config = SingularConfig(apiKey: Constants.APIKEY,
       andSecret: Constants.SECRET) else {         
         return nil
         }     
     //...
     config.conversionValueUpdatedCallback = { conversionValue in
     // Here you have access to the latest conversion value


     }
     //...
     return config
}

- (SingularConfig *)getConfig {
     // Singular Config Options


     SingularConfig* config = [[SingularConfig alloc] initWithApiKey:APIKEY
       andSecret:SECRET];
     //...
     config.conversionValueUpdatedCallback=^(NSNumber *conversionValue, 
       NSNumber *coarse, BOOL lock) {
         // Here you have access to the CV + coarse CV


       };
     //...
     return config;
}

A tabela a seguir resume os cenários possíveis usando essa integração:

// INITIALIZE THE SDK IN THE FOLLOWING SCENEDELEGATE FUNCTIONS]


     
// willConnectTo session


func scene(_ scene: UIScene, willConnectTo session: UISceneSession,
  options connectionOptions: UIScene.ConnectionOptions) {
    let userActivity = connectionOptions.userActivities.first
    // Print IDFV to Console for use in Singular SDK Console


    print(Date(), "-- Scene Delegate IDFV:", 
    UIDevice().identifierForVendor!.uuidString as Any)
    
    //Initialize the Singular SDK here:
    if let config = self.getConfig() {
      config.userActivity = userActivity
      Singular.start(config)
    }
}
      
// continue userActivity


      
func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
  // Starts a new Singular session on continueUserActivity


  if let config = self.getConfig() {
    config.userActivity = userActivity
    Singular.start(config)
  }
}
      
//openURLContexts URLContexts
      
func scene(_ scene: UIScene, openURLContexts URLContexts: 
  Set<UIOpenURLContext>) {
    // Starts a new Singular session on cold start from deeplink scheme


    if let config = self.getConfig() {
      config.openUrl = openurlString
      Singular.start(config)
    }
    
    // Add custom code here to Redirect to non-Singular deep links


    //...
}

// INITIALIZE THE SDK IN THE FOLLOWING WINDOWGROUP FUNCTIONS


var body: some Scene {
    WindowGroup {
        ContentView()
            .onOpenURL(perform: { url in
                openURL = url
                // Initialize Singular from an openURL


                if let config = self.getConfig() {
                    config.openUrl = url
                    Singular.start(config)
                }
            })
    }
    .onChange(of: scenePhase) { oldValue, phase in
        // The SwiftUI ScenePhases replaces the old SceneDelegate lifecycle events


        switch phase {
        case .background:
            print("App Scene: backgrounded")
        case .inactive:
            print("App Scene: inactive")
        case .active:
            print("App Scene: active")
            
            // Initialize Singular


            if let config = self.getConfig() {
                Singular.start(config)
            }
        @unknown default:
            print("App Scene: unknown")
        }
    }
}

// INITIALIZE THE SDK IN THE FOLLOWING SCENEDELEGATE FUNCTIONS


     
// willConnectToSession


- (void)scene:(UIScene *)scene willConnectToSession:(UISceneSession *)session 
  options:(UISceneConnectionOptions *)connectionOptions {
    NSUserActivity* userActivity = [[[connectionOptions userActivities] allObjects] 
      firstObject];
    // Print identifier for Vendor (IDFV) to Xcode Console for use in Singular SDK Console


    NSLog(@"-- Scene Delegate IDFV: %@", [[[UIDevice currentDevice] identifierForVendor] UUIDString]);
    
    // Start a new Singular session from a backgrounded app


    SingularConfig *config = [self getConfig];
    config.userActivity = userActivity;
    [Singular start:config];
}
    
// continueUserActivity


- (void)scene:(UIScene *)scene continueUserActivity:(NSUserActivity *)userActivity{
  // Starts a new Singular session from a backgrounded App


  SingularConfig *config = [self getConfig];
  config.userActivity = userActivity;
  [Singular start:config];
}
    
// openURLContexts


- (void)scene:(UIScene *)scene openURLContexts:(nonnull NSSet *)URLContexts {
  // Starts a new Singular session on cold start from deeplink scheme


  SingularConfig *config = [self getConfig];
  config.openUrl = url;
  [Singular start:config];
  
  // Add custom code here to Redirect to Non-Singular deep links


  //...
}

// INITIALIZE THE SDK IN THE FOLLOWING APPDELEGATE FUNCTIONS


    
// didFinishLaunchingWithOptions


- (BOOL)application:(UIApplication *)application 
  didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // Starts  new session when  user opens the app if session timeout passed/opened using 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 {
      // Starts a new session when the user opens the app using a Singular Link while it was in the background


      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{
    // Starts new session when user opens the app using a non-Singular link, like a traditional app scheme.


    SingularConfig *config = [self getConfig];
    config.openUrl = url;
    [Singular start:config];
    // Add custom code here to Redirect to non-Singular deep links


    //...
    return YES;
}

// INITIALIZE THE SDK IN THE FOLLOWING APPDELEGATE FUNCTIONS


    
// didFinishLaunchingWithOptions


func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) - Bool {
     // Print IDFV to Console for use in Singular SDK Console 


     print(Date(), "-- Scene Delegate IDFV:", UIDevice().identifierForVendor!.uuidString as Any)
     
     //Initialize the Singular SDK here: 
     if let config = self.getConfig() { 
          config.launchOptions = launchOptions 
          Singular.start(config) 
     }
     
     return true
}
    
// continue userActivity


func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([any UIUserActivityRestoring]?) - Void) - Bool {
     
     //Initialize the Singular SDK here: 
     if let config = self.getConfig() {
          config.userActivity = userActivity
          Singular.start(config) 
     }
     
     return true
}
     
// open url


func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) - Bool {
     
     //Initialize the Singular SDK here: 
     if let config = self.getConfig() {
          config.openUrl = url
          Singular.start(config) 
     }
     
     return true
}

No Xcode 15, existe uma nova opção chamada "User Script Sandboxing" que desempenha um papel crucial na construção O objetivo é evitar que os scripts façam alterações não intencionais no sistema, aumentando assim a estabilidade e a segurança da construção. Quando ativado, o sistema de construção restringe os scripts do utilizador para não permitir dependências de entrada/saída não declaradas. Isso é problemático para o SDK Singular, pois ele precisa executar scripts para vincular dependências de forma dinâmica.

Para resolver o problema:

1. Navegue até Configurações de compilação > Opções de compilação.
2. Ajuste "User Script Sandboxing" para um valor "Não"

1. Verifique se o cabeçalho de ponte foi criado.
2. Valide se o arquivo Bridging Header está vinculado em Build Settings > Objective-C Bridging Header.

Em alguns casos, o Simulador iOS exige que arm64 seja excluído em Build Settings > Excluded Architectures.

As Propriedades globais não são exibidas atualmente no Console de teste. Elas serão adicionadas no futuro. Utilize os registos de exportação para validar esta funcionalidade.

Porque é que estou a receber um erro de registo?

Os seguintes erros de registo comuns podem ser ignorados:

• [logging] nome de coluna duplicado: singular_link em "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] nome da coluna duplicado: sequence em "ALTER TABLE events ADD COLUMN sequence INTEGER DEFAULT -1"
• [logging] nome da coluna duplicado: payload em "ALTER TABLE events ADD COLUMN payload TEXT DEFAULT NULL"