1. 下载并安装最新版本的 CocoaPods。

2. 要创建 podfile，请在终端中导航至项目根文件夹，然后键入：

   pod init

3. 要添加 Singular SDK 依赖项，请在项目的 Podfile 中添加以下内容：

   pod 'Singular-SDK'

   例如

   

4. 在终端中，导航至项目根文件夹并运行：

   pod install

5. 从这一点开始，打开 Xcode 工作区文件.xcworkspace来打开项目，而不是 .xcodeproj 文件。
6. 根据以下说明创建Swift 桥接头。

1. 在 Xcode 中，转到 "文件">"添加软件包"，然后输入 Singular SDK GitHub 仓库：

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

   

2. 更新 Singular SDK 版本：

   

3. 单击 "Add Package（添加软件包）"按钮。

4. 转到 "构建阶段"（Build Phases）>"二进制与库链接"（Link Binary with Libraries），然后添加AdServices.framework库。请务必将其标记为可选，因为它仅适用于 iOS 14.3 及更高版本的设备。

   

5. 转到 "构建设置">"链接">"其他链接器标志"，然后用以下项目更新 "其他链接器标志"：
   
   $(inherited) -ObjC -l "sqlite3.0" -l "z" -framework "AdSupport" -framework "Security" -framework "Singular" -framework "StoreKit" -framework "SystemConfiguration" -framework "WebKit" -framework "iAd"

   

   

6. 按照下面的说明创建Swift 桥接头。

您是从 Singular SDK 12.3.2 或更低版本升级的吗？

请按照以下步骤删除旧的静态库

1. 导航到项目文件，删除 Singular 静态库。通常情况下，你应该有一个名为Singular-iOS-sdk-v12.3.2 的文件夹。右键单击该文件夹，将其从项目中删除。
2. 前往下一节安装新框架

首次添加Singular框架

1. 下载并解压 SDK 框架。

   为您的实现选择正确的框架：

   • 对于 Xcode 12 及以上版本，请使用.xcframework [在此下载]。
   • 对于 Xcode 11 及以下版本，使用.framework [DOWNLOAD HERE]。

2. 将解压后的文件夹添加到 Xcode 项目的文件夹中：

   在 Xcode 中，右键单击 "您的应用程序名称">"添加文件到[您的项目名称]"。在打开的对话框中，选择选项 > 创建组，然后添加解压 SDK 的文件夹。
   
   
   
   
   
   现在，Singular 框架应该就在你的项目中了。
   
   

3. 添加所需的库：

   • 在 Xcode 中，选择 "构建阶段"（Build Phases）>"二进制与库链接"（Link Binary With Libraries）。

   • 点击+并添加以下库：

     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. 嵌入并签署 Singular 框架
   • 导航至常规 > 框架、库和嵌入式内容
   • 将奇异框架调整为"嵌入和签名
     
     

如果你使用 CocoaPods 或 Swift 软件包管理器安装了 SDK，你必须为 Swift 创建一个桥接头，以便使用 Singular SDK 中的 Obj-C 库。

1. 在项目中新建一个Header 类型 的文件，并将其命名为YourProjectName-Bridging-Header。

   

2. 打开该文件并添加以下内容：

   #import <Singular/Singular.h>

   例如

   

3. 转到 "构建设置">"Objective-C 桥接头"，然后添加文件的相对路径：

   

如果您想使用应用程序代码自行更新转换值，首先必须在 Singular Config 中设置manualSkanConversionManagement标志。这样，您就可以使用多个 SDK 方法手动检索和更新转换值。

启用手动模式：

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

更新转换值：

在手动模式下，要更新转换值，需要使用skanUpdateConversionValue方法。您可以在应用程序生命周期中任何需要的地方使用该方法。

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

其他 SKAdNetwork 方法：

要获取当前转换值，请使用skanGetConversionValue 方法或conversionValueUpdatedCallback。这两种方法在托管和手动模式下均有效。

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

下表总结了使用此集成的可能方案：

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

在 Xcode 15 中，有一个名为"User Script Sandboxing"（用户脚本沙盒）的新选项，它在构建过程中起着至关重要的作用。其目的是防止脚本对系统进行意外更改，从而增强构建的稳定性和安全性。启用后，构建系统会限制用户脚本，禁止未声明的输入/输出依赖关系。这对 Singular SDK 来说是个问题，因为它需要运行脚本来动态链接依赖关系。

要解决这个问题

1. 导航至 "构建设置" > "构建选项"。
2. 将"用户脚本沙盒"（User Script Sandboxing）调整为"否"。

1. 检查是否创建了桥接头。
2. 在"构建设置">"Objective-C 桥接头"中确认桥接头文件已链接。

在某些情况下，iOS 模拟器要求在 "构建设置">"排除的体系结构"中排除 Arm64。

全局属性目前未显示在测试控制台中。将来会添加。使用导出日志验证此功能。

为什么会出现日志错误？

以下常见日志错误可以忽略：

• [logging] duplicate column name: singular_link in "ALTER TABLE sessions ADD COLUMN singular_link TEXT DEFAULT NULL" 重复列名：singular_link
• [logging] "ALTER TABLE sessions ADD COLUMN payload TEXT DEFAULT NULL" 中的重复列名：payload
• [logging] "ALTER TABLE events ADD COLUMN sequence INTEGER DEFAULT -1" 中重复的列名：sequence
• [logging] "ALTER TABLE events ADD COLUMN payload TEXT DEFAULT NULL" 中的重复列名：payload