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 withLibraries），然后添加AdServices.framework库。 请务必将其标记为 "可选"，因为它仅适用于 iOS 14.3 及更高版本的设备。

   

5. 转到 "构建设置">"链接">"其他链接器标志"，然后用以下项目更新 "其他链接器标志"：

   

   

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 [在此下载] 。

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 (标记为可选，因为它仅适用于 iOS 14.3 及更高版本的设备).

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? {
            // 奇异配置选项

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

- (SingularConfig *)getConfig {
            // 奇异配置选项

            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? {
            // 奇异配置选项

            guard let config = SingularConfig(apiKey: Constants.APIKEY,
                andSecret: Constants.SECRET)
            else {         
                return nil     
            }     
            ...     
            config.conversionValueUpdatedCallback = { conversionValue in
                // 在这里，您可以获得最新的转换值

            }
            ...
            return config
        } 

- (SingularConfig *)getConfig {
    // 奇异配置选项

    SingularConfig* config = [[SingularConfig alloc] initWithApiKey:APIKEY
      andSecret:SECRET];
    ...
  config.conversionValueUpdatedCallback=^(NSNumber *conversionValue, 
    NSNumber *coarse, BOOL lock) {
      // 在这里，您可以获得最新的转换值

    };
    ...
    return config;
  }

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

Singular SDK 还支持非 Singular 提供的通用链接。这是为支持深度链接的合作伙伴（如谷歌广告和Facebook）测量归因所必需的。

对于 Singular iOS SDK 12.0.3 及以上版本，默认支持非 Singular 通用链接。

func getConfig() -> SingularConfig? {
            // 奇异配置选项

            guard let config = SingularConfig(apiKey: Constants.APIKEY,
                andSecret: Constants.SECRET) else {
                return nil
            }
            ...
            config.supportedDomains = ["subdomain.mywebsite.com","anothersubdomain.myotherwebsite.com"]
            ...
            return config
        }

- (SingularConfig *)getConfig {
            // 奇异配置选项

            SingularConfig* config = [[SingularConfig alloc] initWithApiKey:APIKEY
                andSecret:SECRET];
            ...
            config.supportedDomains = @[@"subdomain.mywebsite.com","anothersubdomain.myotherwebsite.com"];
            ...
            return config;
        }

Singular SDK 支持由 ESP（电子邮件服务提供商）提供的通用链接。

ESP 域必须启用 HTTPS。Apple要求iOS 应用程序从支持 HTTPS 的端点拉取 apple-app-site-association 文件，而无需重定向。请咨询您的 ESP，了解他们如何为您的应用程序托管此文件，因为这可能需要在您网站的 DNS 上进行 DNS 配置。通常情况下，ESP 会提供启用 HTTPS 所需的步骤。

要支持 ESP 域，请在 Singular SDK 每次初始化时将自定义跟踪域添加到espDomains配置选项（配置对象中）。

func getConfig() -> SingularConfig? { 
            // 奇异配置选项

            guard let config = SingularConfig(apiKey: Constants.APIKEY,
                andSecret: Constants.SECRET) else { 
                return nil 
            } 
            ... 
            config.espDomains = ["links.mywebsite.com"] 
            ... 
            return config 
        } 

- (SingularConfig *)getConfig { 
            // 奇异配置选项

            SingularConfig* config = [[SingularConfig alloc] initWithApiKey:APIKEY
                andSecret:SECRET]; 
            ... 
            config.espDomains = @[@"links.mywebsite.com"]; 
            ... 
            return config; 
        } 

// 在以下 scenedelegate 函数中初始化 sdk

     
// willConnectTo session

func scene(_ scene: UIScene, willConnectTo session: UISceneSession,
  options connectionOptions: UIScene.ConnectionOptions) {
    let userActivity = connectionOptions.userActivities.first
    // 将 IDFV 打印到控制台，供 Singular SDK 控制台使用

    print(Date(), "-- Scene Delegate IDFV:", 
    UIDevice().identifierForVendor!.uuidString as Any)
    
    // 在此初始化 Singular SDK：

    if let config = self.getConfig() {
      config.userActivity = userActivity
      Singular.start(config)
    }
}
      
// continue userActivity

      
func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
  // 通过 continueUserActivity 启动新的 Singular 会话

  if let config = self.getConfig() {
    config.userActivity = userActivity
    Singular.start(config)
  }
}
      
//openURLContexts URLContexts
      
func scene(_ scene: UIScene, openURLContexts URLContexts: 
  Set<UIOpenURLContext>) {
    // 从深层链接计划冷启动时启动新的 Singular 会话

    if let config = self.getConfig() {
      config.openUrl = openurlString
      Singular.start(config)
    }
    
    // 在此处添加自定义代码，重定向至非星形深层链接

    //...
}

// 在以下窗口组函数中初始化 sdk

var body: some Scene {
    WindowGroup {
        ContentView()
            .onOpenURL(perform: { url in
                openURL = url
                // 从打开的 URL 初始化 Singular

                if let config = self.getConfig() {
                    config.openUrl = url
                    Singular.start(config)
                }
            })
    }
    .onChange(of: scenePhase) { oldValue, phase in
        // SwiftUI ScenePhases 取代了旧的 SceneDelegate 生命周期事件

        switch phase {
        case .background:
            print("应用程序场景：有背景")
        case .inactive:
            print("应用程序场景：不活动")
        case .active:
            print("应用程序场景：活动")
            
            // 初始化奇异

            if let config = self.getConfig() {
                Singular.start(config)
            }
        @unknown default:
            print("应用程序场景：未知")
        }
    }
}

// 在以下 scenedelegate 函数中初始化 sdk

     
// willConnectToSession

- (void)scene:(UIScene *)scene willConnectToSession:(UISceneSession *)session 
  options:(UISceneConnectionOptions *)connectionOptions {
    NSUserActivity* userActivity = [[[connectionOptions userActivities] allObjects] 
      firstObject];
    // 将供应商标识符 (IDFV) 打印到 Xcode 控制台，供 Singular SDK 控制台使用

    NSLog(@"-- Scene Delegate IDFV: %@", [[[UIDevice currentDevice] identifierForVendor] UUIDString]);
    
    // 从后台应用程序启动新的 Singular 会话

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

- (void)scene:(UIScene *)scene continueUserActivity:(NSUserActivity *)userActivity{
  // 从后台应用程序启动新的 Singular 会话

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

- (void)scene:(UIScene *)scene openURLContexts:(nonnull NSSet *)URLContexts {
  // 从深层链接计划冷启动时启动新的 Singular 会话

  SingularConfig *config = [self getConfig];
  config.openUrl = url;
  [Singular start:config];
  
  // 在此处添加自定义代码，重定向至非星形深层链接

  //...
}

// 在以下 appdelegate 函数中初始化 sdk

    
// didFinishLaunchingWithOptions

- (BOOL)application:(UIApplication *)application 
  didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // 如果会话超时或使用奇异链接打开，则在用户打开应用时启动新会话

    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 {
      // 当用户在后台使用奇异链接打开应用程序时，启动一个新会话

      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{
    // 当用户使用非星形链接（如传统的应用程序方案）打开应用程序时，启动新会话。

    SingularConfig *config = [self getConfig];
    config.openUrl = url;
    [Singular start:config];
    // 在此处添加自定义代码，重定向至非星形深层链接

    //...
    return YES;
}

Singular 可以通过服务器到服务器集成接收额外的移动事件跟踪数据。要使用此功能，必须将用户 ID 映射到 Singular 的移动设备跟踪标识符。

setDeviceCustomUserId("custom_user_id")

[Singular setDeviceCustomUserId:@"a_user_id"];

使用revenue和customRevenue方法，您可以手动指定交易金额和货币，以及可选的其他详细信息，如产品序列号和数量等。customRevenue方法还允许您传递自定义事件名称。

请注意，如果使用这些方法，Singular 不会获得交易收据，也无法验证交易。

// 没有产品详细信息的收入

Singular.revenue("USD",amount:1.99)
          
// 包含产品详细信息的收入

Singular.revenue("EUR",amount:5.00, productSKU:"SKU1928375", 
  productName:"Reservation Fee",productCategory:"Fee", productQuantity:1, productPrice:5.00)
          
// 发送带有字典中属性的收入事件

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)

// 没有产品详细信息的收入

[Singular revenue:@"USD" amount:1.99];
          
// 包含产品详细信息的收入

[Singular revenue:@"EUR" amount:5.00 productSKU:@"SKU1928375"
  productName:@"Reservation Fee" productCategory:@"Fee" productQuantity:1 productPrice:5.00];
          
// 发送带有字典中属性的收入事件

NSMutableDictionary *dic = [[NSMutableDictionary alloc] init];
[dic setValue:@"100% Organic Cotton Mixed Plaid Flannel Shirt"
  forKey:ATTRIBUTE_SNG_ATTR_ITEM_DESCRIPTION];
[dic setValue:@"$69.95" forKey:ATTRIBUTE_SNG_ATTR_ITEM_PRICE];
[dic setValue:@"5 Star" forKey:ATTRIBUTE_SNG_ATTR_RATING];
[dic setValue:@"Flannel Shirt" forKey:ATTRIBUTE_SNG_ATTR_SEARCH_STRING];
[Singular revenue:@"USD" amount:19.99 withAttributes:dic];

// 具有自定义名称且无产品详细信息的收入

Singular.customRevenue("MyCustomRevenue", currency:"USD", amount:1.99)
          
// 具有自定义名称和产品详细信息的收入

Singular.customRevenue("MyCustomRevenue", currency:"EUR", amount:5.00, productSKU:"SKU1928375",
  productName:"Reservation Fee", productCategory:"Fee", productQuantity:1, productPrice:5.00)
          
// 发送带有字典中属性的自定义收入事件

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)

// 具有自定义名称且无产品详细信息的收入

[Singular customRevenue:@"MyCustomRevenue" currency:@"USD" amount:1.99];
          
// 具有自定义名称和产品详细信息的收入

[Singular customRevenue:@"MyCustomRevenue" currency:@"EUR" amount:5.00 productSKU:@"SKU1928375"
  productName:@"Reservation Fee" productCategory:@"Fee"  productQuantity:1 productPrice:5.00];
          
// 发送带有字典中属性的自定义收入事件

NSMutableDictionary *dic = [[NSMutableDictionary alloc] init];
[dic setValue:@"100% Organic Cotton Mixed Plaid Flannel Shirt" forKey:ATTRIBUTE_SNG_ATTR_ITEM_DESCRIPTION];
[dic setValue:@"$69.95" forKey:ATTRIBUTE_SNG_ATTR_ITEM_PRICE];
[dic setValue:@"5 Star" forKey:ATTRIBUTE_SNG_ATTR_RATING];
[dic setValue:@"Flannel Shirt" forKey:ATTRIBUTE_SNG_ATTR_SEARCH_STRING];
[Singular customRevenue:@"MyCustomRevenue" currency:@"USD" amount:44.99 withAttributes:dic];

Singular可以收集来自服务器的收入数据，帮助分析营销活动的表现和投资回报率。

要求：

• 从应用内注册或登录事件中捕获并传递设备标识符，并将此数据与服务器上的用户 ID 一起存储。由于用户的设备标识符可能会发生变化，因此请确保在用户生成应用程序会话时更新标识符。这将确保服务器端事件归属于正确的设备。
• 服务器端事件是平台特定的，只能使用与设备平台相匹配的设备标识符发送（如 iOS 设备的 IDFA 或 IDFV）。
• 您可以使用 Singular 内部 BI 回传机制将事件实时推送到内部端点，以便更新服务器端的数据集。请参阅内部 BI 回传常见问题。
• 查看服务器到服务器集成指南中的"跟踪收入 "部分，了解详情。

请点击以下链接了解如何启用这些合作伙伴。

• 在RevenueCat文档中了解更多信息。
• 在adapty 文档中了解更多信息。

要使 Segment 能与 Singular SDK 并行发送事件到 Singular，必须在 Segment 中添加一个"云模式 "目的地。请点击此处查看我们的指南。

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

要解决这个问题

1. 导航至Build Settings > Build Options.
2. 将"User Script Sandboxing" 调整为"No"

1. 检查是否创建了桥接标头。
2. 验证桥接标头文件是否链接到Build Settings > Objective-C Bridging Header.

在某些情况下，iOS 模拟器要求在Build Settings > Excluded Architectures 中排除 arm64。

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

您可以忽略此错误，因为当 SKAdNetwork 未看到广告系列的印象时，预计会出现此错误（请参阅Apple 对此问题的答复）。

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

• [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"