Iterable iOS SDK

iterable-ios-sdk是Iterable的iOS客户端Objective-C实现，适用于iOS 7.0及以上版本。

Iterable中设置推送集成

在开始使用SDK之前，您需要

1. 设置您的应用程序以接收推送通知，并
2. 在Iterable中设置推送集成。这允许Iterable为您代表与Apple的推送通知服务进行通信

如果您还没有这样做，您需要为您的应用程序启用推送通知。这可以通过在Xcode的您的目标的能力下切换推送通知来完成。您也可以直接在Apple的成员中心中的App Center中这样做；转到标识符 -> 应用ID -> 选择您的应用。您应该在应用程序服务下看到推送通知。点击编辑并启用推送通知。

您还需要为推送服务生成SSL证书和私钥。有关详细信息，请参阅本节末尾的链接。

一旦你设置了APNS证书，请访问Iterable中的集成 -> 移动推送。在创建集成时，你需要选择一个名称和一个平台。名称完全由你决定；当你在我们的SDK中使用registerToken时，它将是appName。平台可以是APNS或APNS_SANDBOX；这些对应于生产环境和沙盒平台。你的应用程序将根据是否使用开发证书或分发配置文件来构建生成不同的令牌。

有关更多信息，请参阅

• 配置推送通知
• 创建证书
• 亚马逊创建证书指南

恭喜你，你已经配置了你的移动应用程序以接收推送通知！现在，让我们设置Iterable SDK...

自动安装（通过CocoaPods）

Iterable支持CocoaPods以简化安装。如果您还没有，可以使用Ruby通过运行

$ sudo gem install cocoapods 

为了将Iterable SDK包含到项目中，您需要在您的Podfile中添加它。如果您还没有，可以通过运行创建一个：

$ pod init

要在目标中添加Iterable pod，编辑Podfile并在目标下方包含这一行

pod 'IterableSDK'

现在，您需要告诉CocoaPods安装依赖项

$ pod install

恭喜！现在您已经将Iterable SDK导入到您的项目中！

ℹ如果您的项目是用Swift编写的，您将需要一个bridging header。有关创建bridging header的更多信息，请参阅此处。

手动安装

在Artifacts目录中，您可以找到编译后的静态库和头文件。要将其包含到项目中...

1. 添加头文件到您的头文件搜索路径。《构建设置》 -> 《搜索路径》 -> 《头文件搜索路径》。输入您放置SDK头文件的位置。您应该启用递归（它将在路径末尾添加**）。
2. 将项目链接到Iterable的SDK。有两种方法可以做到这一点。
3. 转到《构建阶段》 -> 《链接二进制与库》并选择libIterable-iOS-SDK.a，或者
4. 转到《构建设置》 -> 《搜索路径》 -> 《库搜索路径》，并输入libIterable-iOS-SDK.a的位置。然后，通过转到《构建设置》 -> 《链接》 -> 《其他链接器标志》，告诉项目在链接阶段查找Iterable-iOS-SDK，并添加-lIterable-iOS-SDK
5. 前往 构建设置 -> 链接 -> 其他链接器标志，并添加 -ObjC。这对于在链接过程中正确选择 NSData+Conversion.h 分类是必须的。有关更多信息，请参阅这里。

使用 SDK

1. 在应用程序启动时（application:didFinishLaunchingWithOptions:），初始化 Iterable SDK

IterableConfig *config = [[IterableConfig alloc] init];
config.pushIntegrationName = "myPushIntegration";
[IterableAPI initializeWithApiKey:@"<your-api-key>" launchOptions:launchOptions config:config];

• apiKey 应与 Iterable 项目的 API 密钥对应。如果您愿意，可以根据是否构建在 DEBUG 或 PRODUCTION，指定不同的 apiKey，并将 SDK 指向相关的 Iterable 项目。
• 最好在该方法从 application:didFinishLaunchingWithOptions: 中调用并将 launchOptions 传入。这将允许 SDK 自动跟踪从远程 Iterable 推送通知启动的应用程序。
• 此方法为您创建了一个单例 IterableAPI。您可以使用 [IterableAPI sharedInstance] 在以后检索它。如果您以后要检索它，请确保您已经将其实例化过，或者检查非空返回值。

2. 一旦您知道了用户的电子邮件 (首选) 或 userId，调用 setEmail: 或 setUserId:

• 电子邮件： [[IterableAPI sharedInstance] setEmail:@"[email protected]"];
• 用户ID： [[IterableAPI sharedInstance] setUserId:@"userId"];
  • 如果您正在设置 userId，则该 userId 必须已经存在一个现有用户。
  • 首选使用电子邮件，因为这不需要在后端进行基于 userId 的附加查找。

3. 注册远程通知
   从 iOS 10 开始，首选方法是使用 UserNotifications 框架。请参阅 Apple 文档中的请求使用通知权限和将您的应用程序注册到 APNs。

   1. 使用 UNUserNotificationCenter 的 requestAuthorizationWithOptions:completionHandler: 请求通过显示通知的授权。您第一次调用此方法时，iOS 将提示用户允许特定的交互。操作系统将通过提供的回调块异步通知您用户的选择。
      对于 iOS < 10，调用 UIApplication 的 registerUserNotificationSettings:
   2. 调用 UIApplication 的 registerForRemoteNotifications 方法以将您的应用程序注册为远程通知。
   3. 使用您的应用程序代理的 application:didRegisterForRemoteNotificationsWithDeviceToken: 方法来接收传递远程通知所需的设备令牌。使用application:didFailToRegisterForRemoteNotificationsWithError: 方法处理错误。

   ⚠设备注册将会失败，如果用户邮箱或userId未设置。如果您在应用启动后（即用户登录时）调用setEmail:或setUserId:，请确保再次调用registerForRemoteNotifications以将设备注册到登录用户。

4. 将令牌发送到Iterable
   使用SDK的- (void)registerToken:(NSData *)token将令牌发送到 Iterable
   这将使用传递给pushIntegrationName的集成注册令牌。如果您还传递了sandboxPushIntegrationName，Iterable SDK将尝试从 provisioning profile 中确定APNS环境，并使用正确的集成（APNS或APNS_SANDBOX）注册设备。
   设备令牌可能会更改，因此您的应用在每次启动时都需要重新注册，并将收到的令牌发送回您的服务器。不要在设备上缓存令牌；每次收到令牌时都要发送。这是苹果推荐的做法；请参阅文档此处。具体来说，

   ⚠设备令牌可能会更改，因此您的应用在每次启动时都需要重新注册，并将接收到的令牌发送回您的服务器。如果您未能更新设备令牌，远程通知可能无法到达用户的设备。当用户将备份数据恢复到新设备或电脑，或是重新安装操作系统时，设备令牌总是会更改。在迁移数据到新设备或电脑时，用户必须先启动您的应用一次，远程通知才能发送到该设备。

   ⚠不要缓存设备令牌；每次需要时都从系统中获取令牌。如果您的应用已注册远程通知，再次调用registerForRemoteNotifications方法不会产生任何额外的开销，iOS会立即将现有的设备令牌返回给您的app delegate。此外，当设备令牌更改时，iOS还会调用您的delegate方法，而不仅是在应用注册或重新注册时。

5. 处理推送交互 当用户点击通知或其中一个操作按钮时，系统会调用UNUserNotificationCenterDelegate的userNotificationCenter:didReceiveNotificationResponse:withCompletionHandler:。将此调用传递给IterableAppIntegration以跟踪推送打开事件并执行相关操作（以下提供自定义操作和URL代理的示例）。

整合一切

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // other setup tasks here....
    
    // Initialize Iterable SDK
    IterableConfig *config = [[IterableConfig alloc] init];
    config.pushIntegrationName = "myPushIntegration_Prod";
    config.sandboxPushIntegrationName = "myPushIntegration_Dev";
    [IterableAPI initializeWithApiKey:@"YOUR API KEY" launchOptions:launchOptions config:config];
 
    if (@available(iOS 10, *)) {
    	UNUserNotificationCenter *center = [UNUserNotificationCenter currentNotificationCenter];
        center.delegate = self;
        [center requestAuthorizationWithOptions:(UNAuthorizationOptionAlert | UNAuthorizationOptionBadge | UNAuthorizationOptionSound) completionHandler:^(BOOL granted, NSError * _Nullable error){
             if(!error){
                 [[UIApplication sharedApplication] registerForRemoteNotifications];
             }
         }];  
    } else {
	    UIUserNotificationType types = UIUserNotificationTypeBadge |
	                 UIUserNotificationTypeSound | UIUserNotificationTypeAlert;
	    UIUserNotificationSettings *mySettings =
	                [UIUserNotificationSettings settingsForTypes:types categories:nil];
	    [[UIApplication sharedApplication] registerUserNotificationSettings:mySettings];
    	[[UIApplication sharedApplication] registerForRemoteNotifications];
    }
 
    // Register for remote notifications.
}
 
// Handle remote notification registration.
- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)token {
    [[IterableAPI sharedInstance] registerToken:token];
}
 
- (void)application:(UIApplication *)application didFailToRegisterForRemoteNotificationsWithError:(NSError *)error {
    NSLog(@"Error in registration for remote notifications. Error: %@", error);
}

// This is necessary for push notifications to work while the app is in foreground
- (void)userNotificationCenter:(UNUserNotificationCenter *)center willPresentNotification:(UNNotification *)notification withCompletionHandler:(void (^)(UNNotificationPresentationOptions options))completionHandler{
    completionHandler(UNAuthorizationOptionAlert | UNAuthorizationOptionBadge | UNAuthorizationOptionSound);
}

// Pass the notification response (tap on the notification or one of the buttons) to the Iterable SDK so it can track the push open event and perform the associated action
- (void)userNotificationCenter:(UNUserNotificationCenter *)center didReceiveNotificationResponse:(UNNotificationResponse *)response withCompletionHandler:(void(^)())completionHandler{
    [IterableAppIntegration userNotificationCenter:center didReceiveNotificationResponse:response withCompletionHandler:completionHandler];
}

// This method will be called when the notification is opened on iOS < 10
- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
	[IterableAppIntegration application:application didReceiveRemoteNotification:userInfo fetchCompletionHandler:completionHandler];
}

恭喜！您现在可以从Iterable向您的设备发送远程推送通知了！

Iterable通知

Iterable的所有通知都将带有 payload 中的itbl字段。此字段将包含可供 Iterable 使用的数据字典。您可以直接访问它，但应避免这样做，因为这些字段可能会更改。目前，字段包括

• campaignId - 营销活动ID（在Iterable中）。对于校对和测试推送不相关。
• templateId - 模板ID（在Iterable中）。对于测试推送不相关。
• messageId - 消息ID（在Iterable中）。
• isGhostPush - 是否为幽灵推送。参见下文关于卸载跟踪的章节。

卸载跟踪

Iterable将会在无需您额外操作的情况下跟踪卸载。

这是通过在原始活动发送一段时间（目前是12小时）后的第二次推送通知来实现的。如果我们收到设备令牌不再有效的反馈，我们将该设备的卸载分配给最新的活动，归因于最近的十二小时内。一个“真实”的活动推送（与稍后的“幽灵”发送相对）也可以触发记录卸载。在这种情况下，如果在归因期内没有之前的活动，卸载仍然会被跟踪，但不会归因于任何活动。

这些“幽灵”通知将不会自动在设备上创建通知。事实上，除非您启用了后台模式，否则您的应用程序甚至不会收到通知。如果您希望应用程序接收并对这些“幽灵”推送做出响应，您可以启用后台模式（这不会使通知显示出来；它只会让您的应用程序处理它们）。为了做到这一点，请前往Xcode中的目标，然后前往 功能 -> 后台模式 并启用 后台获取 和 远程通知。

启用后台模式后，您需要实现一个不同的方法来代替 application:didReceiveRemoteNotification:；这个方法是 application:didReceiveRemoteNotification:fetchCompletionHandler:。这个方法与 application:didReceiveRemoteNotification: 不同，不论您的应用程序是否在后台或前台运行都会被调用。完成后，不要忘记使用 UIBackgroundFetchResult 调用完成处理程序。有关后台模式通知的更多信息，请参阅该方法的文档 下的 讨论 部分。

禁用向设备推送通知

当用户注销时，您通常希望禁用对该用户/设备的推送通知。这可以通过调用 disableDeviceForCurrentUser 完成。请注意，只有在您之前调用过 registerToken 时，它才会尝试禁用该设备。

为了重新启用该设备的推送通知，只需像用户再次登录时那样正常调用 registerToken 即可。

App 内通知

要显示用户的 App 内通知，请调用 spawnInAppNotification 并传递一个定义的 ITEActionBlock 回调处理器。当用户在通知上点击按钮时，定义的处理程序被调用，并传入 InApp 模板中定义的操作名称。

当通过 spawnInAppNotification 调用通知时，InApp 会自动打开并跟踪按钮点击。使用 spawnInAppNotification，通知会被消耗并从用户的 App 内消息队列中移除。如果您想保留队列中的消息，请考虑直接使用 getInAppMessages。如果您使用 getInAppMessages，您将需要在回调处理程序中手动管理 App 内打开。

追踪和更新用户字段

可以使用 track 函数跟踪自定义事件，并使用 updateUser 函数修改用户字段。

深度链接

处理推送通知中的链接

推送通知和操作按钮可能附加有 openUrl 操作。当指定一个 URL 时，SDK 将首先调用您在 IterableConfig 对象中指定的 urlDelegate。您可以使用该代理以与其他正常深度链接相同的方式处理 openUrl 操作。如果未设置代理或返回 NO，则 SDK 将使用该 URL 打开 Safari。

// AppDelegate.m
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    ...
    // Initialize Iterable SDK
    IterableConfig *config = [[IterableConfig alloc] init];
    ...
    config.urlDelegate = self;
    [IterableAPI initializeWithApiKey:@"YOUR API KEY" launchOptions:launchOptions config:config];
    ...
}

- (BOOL)handleIterableURL:(NSURL *)url context:(IterableActionContext *)context {
    // Assuming you have a DeeplinkHandler class that handles all deep link URLs and navigates to the right place in the app
    return [[DeeplinkHandler sharedInstance] handleUrl:url];
}

处理电子邮件链接

为了使电子邮件中的链接和链接重写一起工作，您需要设置 Iterable 项目的 apple-app-site-association 文件。更多信息请参阅此处：[设置 iOS 通用链接](https://support.iterable.com/hc/en-us/articles/115000440206-Setting-up-iOS-Universal-Links)。

如果您已经设置了 urlDelegate（参见上文的 处理推送通知中的链接 部分），则可以使用相同的处理程序来处理电子邮件深度链接，通过在您的 UIApplicationDelegate 中调用 application:continueUserActivity:restorationHandler:

- (BOOL)application:(UIApplication *)application
 		continueUserActivity(NSUserActivity *)userActivity 
 		restorationHandler:(void (^)(NSArray *restorableObjects))restorationHandler {
    // This will track the click, retrieve the original URL and call `handleIterableURL:context:` with the original URL
    return [IterableAPI handleUniversalLink:userActivity.webpageURL];
}

或者，配合回调函数调用 getAndTrackDeeplink 来处理原始深度链接 URL。您可以为任何传入的 URL 使用此方法，因为它将执行回调而不会更改非可迭代 URL 的 URL。

Swift

func application(_ application: UIApplication, continue userActivity: NSUserActivity,
                  restorationHandler: @escaping ([Any]?) -> Void) -> Bool {
    
    IterableAPI.getAndTrackDeeplink(userActivity.webpageURL!, callbackBlock: {
        (originalURL) in
            //Handle Original URL deeplink here
    });
    return true
}

Objective-C

- (BOOL)application:(UIApplication *)application
 		continueUserActivity(NSUserActivity *)userActivity 
 		restorationHandler:(void (^)(NSArray *restorableObjects))restorationHandler {
    
    [IterableAPI getAndTrackDeeplink:iterableLink callbackBlock:^(NSString* originalURL) {
        //Handle Original URL deeplink here
    }];
    
    return true;
}

丰富推送通知

推送通知可能包含带有图片、动画 GIF 或视频的多媒体附件，并且在未来更新中，将有创建动作按钮的方法。为了在您的应用内工作，您需要创建一个通知服务扩展。更多说明请在此处： iOS 10 和 Android 中的丰富推送通知 - 媒体附件。
Iterable SDK 提供了处理媒体附件和动作按钮的实现，因此您只需继承它

Podfile

// If the target name for the notification extension is 'MyAppNotificationExtension'
target 'MyAppNotificationExtension' do
    pod 'IterableAppExtensions'
end

NotificationService.h

#import <UserNotifications/UserNotifications.h>
#import <IterableAppExtensions/IterableExtensions.h>

@interface NotificationService : ITBNotificationServiceExtension

@end

附加信息

有关更多信息，请参阅我们的 设置指南。

有关推送通知设置的相关常见问题，请参阅我们的 推送通知设置 FAQ。

许可证

麻省理工学院许可证

查看 LICENSE

想贡献力量吗？

这个库是开源的，我们会审阅拉取请求！

有关更多信息，请参阅 CONTRIBUTING