GMP Push SDK 是 GMP 提供端触达能力的 SDK

1. 通道配置

在gmp后台管理中心-通道管理-AppPush-新增应用如下图所示，应用名称填写便于标识的名称即可，pushAppId 需要唯一，需要注意的是pushAppId需要和后续接入 sdk 配置中使用的appid一致

然后选中新建的应用将 iOS 通道的配置信息填写完整，Topic 和 Sandbox Topic 填 app 的包名，KeyId、teamId、AuthKey 从苹果开发者后台获取。

1. 集成 SDK

1.1 集成 Finder SDK

PushSDK 依赖 Finder SDK 进行数据回流，在使用PushSDK 前，请确保已经集成了 Finder SDK。

Finder iOS SDK接入指南地址：Finder 接入

1.2 集成 GMP Push SDK

1.2.1 引入库

现在接入方式已经支持cocoapods的方式进行依赖库的引入，SDK 内部有两个对应的子库，分别为Core子库和对应用于notification service extension的extension子库，请分别在不同的 targer 引入对应的子库，引入示例：

//需要额外添加一个这两个source
source 'https://github.com/CocoaPods/Specs.git'
source 'https://github.com/volcengine/volcengine-specs.git'

# 在主工程 target 中引入 Core 子库
target 'MainTarget' do 
	pod 'BDUGPushSDK-tob' ,'0.0.2-rc.1' ,: subspec => [
    'Core', #必须集成
    'Finder' #若集成此子库，会使用 Finder SDK 进行数据上报，若不集成，需自己实现数据上报功能，详见
	]
end

# 在 notification service extension 的 target 中引入 Extension 子库
target 'NotificationServiceExtension' do
	pod 'BDUGPushSDK-tob' ,'0.0.2-rc.1' ,: subspec => [
    'Extension'
	]
end 

1.2.2 Xcode 工程配置

请确保对应的app证书也有对应的推送能力
如使用 Xcode 8 及以上环境开发，请开启 Application Target 的 Capabilities->Push Notifications 选项，如图：

2. 初始化SDK

2.1 获取初始化必备 id

2.1.1 获取 Push 应用 id

弹窗应用 id 即为新增弹窗应用时填入的 PushAppId

2.1.2 获取 mainAccountId

进入火山引擎控制台，点击右上角头像 icon，红框中的账号 ID 即是 mainAccountId

2.2 初始化

PushSDK需要在iOS工程中的AppDelegate类中进行初始化操作。
PushSDK 依赖于 Finder SDK 的 id 信息（如 did、iid），所以请在 Finder SDK 完成设备注册的回调中进行 PushSDK 的初始化，示例代码如下：

2.2.1 初始化示例（私有化版本）

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
		// finder 设备注册完成回调
	  [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(onRegisterSuccess:) name:BDAutoTrackNotificationRegisterSuccess object:nil];
	  BDAutoTrackConfig *config = [BDAutoTrackConfig configWithAppID:@"your_app_id" launchOptions:launchOptions];
<Attachment link="https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_96f4107ad63d0f06f03d29c5c923f974.zip" name="PushSDK接入Demo.zip" size="194.53KB"></Attachment>	  config.appName = @"your_app_name"; // 与您申请APPID时的app_name一致
	  config.channel = @"App Store"; // 线上环境使用 "App Store", debug 时传入 "sandbox"
	  config.showDebugLog = NO; // 是否在控制台输出日志，仅调试使用，需要同时设置logger。release版本请设置为 NO
	  config.logNeedEncrypt = YES; // 是否加密日志，默认加密。release版本请设置为 YES
	  config.autoTrackEnabled = YES; //是否开启全埋点采集用于圈选功能
	  [BDAutoTrack startTrackWithConfig:config];
  
	  // 务必在初始化前设置好代理对象
	  [BDUGPushService setNotificationDelegate:self];
    BDUGRequestParam *param = [BDUGRequestParam requestParam];
    param.aId = @"Your AppID";
    param.channel = @"App Store";
    param.appName = @"Your AppName";
    // 注意，这个需要自己设置自己的域名 
    param.host = @"https://xxx.com";
    // 使用了Notification Service Extension用于UID精准推送及真实到达统计
    // 业务方设置自己App的App Groups中的一个值即可
    [BDUGPushService setAppGroupKey:@"group.bdug.pushtest"];

    //确保SDK初始化在主线程
    if (![[NSThread currentThread] isMainThread]) {
        dispatch_sync(dispatch_get_main_queue(), ^{
            [BDUGPushService startPushServiceWithParam:param];
            // 如需配置category，创建config参数，不需要配置传nil即可
            [BDUGPushService registerBDUGPushSDKWith:nil];
        });
    } else {
        [BDUGPushService startPushServiceWithParam:param];
        // 如需配置category，创建config参数，不需要配置传nil即可
        [BDUGPushService registerBDUGPushSDKWith:nil];
    }
    
    // 设置应用小红点的数字，-1 即为清空消息
    [BDUGPushService setBadgeNumber:-1];
}

- (void)onRegisterSuccess:(NSNotification *)noti {
    NSString *did = [noti.userInfo objectForKey:kBDAutoTrackNotificationRangersDeviceID]; //deviceid

    // deviceId installId ssid uuid uuidType 这些请在设备注册完毕之后配置 然后初始化SDK
    [BDUGPushService updateDeviceId:did ssid:[BDAutoTrack ssid] uuid:@"uuid" uuidType:@"id_type"];
}

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
			// finder 设备注册完成回调
			NotificationCenter.default.addObserver(self, selector: #selector(onRegisterSuccess(_:)), name: Notification.Name(BDAutoTrackNotificationRegisterSuccess), object: nil)
	    let config = BDAutoTrackConfig(appID: AppInfo.finderAppId, launchOptions: launchOptions) // 如不清楚请联系专属客户成功经理
      config.serviceVendor = BDAutoTrackServiceVendorCN //数据上报
	    config.appName = "your_app_name" // 与您申请APPID时的app_name一致
	    config.channel = "App Store" // 线上环境使用 "App Store", debug 时传入 "sandbox"
	    config.showDebugLog = false // 是否在控制台输出日志，仅调试使用，需要同时设置logger。release版本请设置为 NO
	    config.logNeedEncrypt = true // 是否加密日志，默认加密。release版本请设置为 YES
	    config.autoTrackEnabled = true //是否开启全埋点采集用于圈选功能
      
      // 务必在初始化前设置好代理对象
      BDUGPushService.setNotificationDelegate(**self**)
      let param = BDUGRequestParam()
      param.aId = "Your AppID"
      param.channel = "App Store"
      param.appName = "Your AppName"
      // 注意，这个需要自己设置自己的域名 
      param.host = "https://xxx.com"
      // 使用了Notification Service Extension用于UID精准推送及真实到达统计
      // 业务方设置自己App的App Groups中的一个值即可
      BDUGPushService.setAppGroupKey(AppInfo.appGroupKey)
          
			//确保SDK初始化在主线程
      if (!Thread.current.isMainThread) {
		      DispatchQueue.main.async {
		          BDUGPushService.start(with: param)
		          // 如需配置category，创建config参数，不需要配置传nil即可
		          BDUGPushService.registerBDUGPushSDK(with: **nil**)
		      }
      } else {
          BDUGPushService.start(with: param)
          // 如需配置category，创建config参数，不需要配置传nil即可
          BDUGPushService.registerBDUGPushSDK(with: **nil**)
      }

      // 设置应用小红点的数字，-1 即为清空消息
      BDUGPushService.setBadgeNumber(-1)
}
    
@objc func onRegisterSuccess(_ noti: Notification) {
    let did = noti.userInfo?[kBDAutoTrackNotificationRangersDeviceID] ?? ""
    // deviceId installId ssid uuid uuidType 这些请在设备注册完毕之后配置 然后初始化SDK
    BDUGPushService.updateDeviceId(did, ssid: BDAutoTrack.ssID ?? "", uuid: "uuid", uuidType: "uuid type")
}

2.2.2 初始化示例（SaaS版本）

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
		// finder 设备注册完成回调
	  [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(onRegisterSuccess:) name:BDAutoTrackNotificationRegisterSuccess object:nil];
	  BDAutoTrackConfig *config = [BDAutoTrackConfig configWithAppID:@"your_app_id" launchOptions:launchOptions];
	  config.serviceVendor = BDAutoTrackServiceVendorCN; //数据上报
	  config.appName = @"your_app_name"; // 与您申请APPID时的app_name一致
	  config.channel = @"App Store"; // 线上环境使用 "App Store", debug 时传入 "sandbox"
	  config.showDebugLog = NO; // 是否在控制台输出日志，仅调试使用，需要同时设置logger。release版本请设置为 NO
	  config.logNeedEncrypt = YES; // 是否加密日志，默认加密。release版本请设置为 YES
	  config.autoTrackEnabled = YES; //是否开启全埋点采集用于圈选功能
	  [BDAutoTrack startTrackWithConfig:config];
  
	  // 务必在初始化前设置好代理对象
	  [BDUGPushService setNotificationDelegate:self];
    BDUGRequestParam *param = [BDUGRequestParam requestParam];
    param.aId = @"Your AppID"; //这里的 aid 要与gmp后台通道配置时设置的 push appid一致
    param.channel = @"App Store";
    param.appName = @"Your AppName";
    param.mainAccountId = @"main_account_id"; // saas 版本的主账号 id
    param.host = GMPSaaSHost;
    // 使用了Notification Service Extension用于UID精准推送及真实到达统计
    // 业务方设置自己App的App Groups中的一个值即可
    [BDUGPushService setAppGroupKey:@"group.bdug.pushtest"];

    //确保SDK初始化在主线程
    if (![[NSThread currentThread] isMainThread]) {
        dispatch_sync(dispatch_get_main_queue(), ^{
            [BDUGPushService startPushServiceWithParam:param];
            // 如需配置category，创建config参数，不需要配置传nil即可
            [BDUGPushService registerBDUGPushSDKWith:nil];
        });
    } else {
        [BDUGPushService startPushServiceWithParam:param];
        // 如需配置category，创建config参数，不需要配置传nil即可
        [BDUGPushService registerBDUGPushSDKWith:nil];
    }
    
    // 设置应用小红点的数字，-1 即为清空消息
    [BDUGPushService setBadgeNumber:-1];
}

- (void)onRegisterSuccess:(NSNotification *)noti {
    NSString *did = [noti.userInfo objectForKey:kBDAutoTrackNotificationRangersDeviceID]; //deviceid

    // deviceId installId ssid uuid uuidType 这些请在设备注册完毕之后配置 然后初始化SDK
    [BDUGPushService updateDeviceId:did ssid:[BDAutoTrack ssID] uuid:@"uuid" uuidType:@"id_type"];
}

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
			// finder 设备注册完成回调
			NotificationCenter.default.addObserver(self, selector: #selector(onRegisterSuccess(_:)), name: Notification.Name(BDAutoTrackNotificationRegisterSuccess), object: nil)
	    let config = BDAutoTrackConfig(appID: AppInfo.finderAppId, launchOptions: launchOptions) // 如不清楚请联系专属客户成功经理
      config.serviceVendor = BDAutoTrackServiceVendorCN //数据上报
	    config.appName = "your_app_name" // 与您申请APPID时的app_name一致
	    config.channel = "App Store" // 线上环境使用 "App Store", debug 时传入 "sandbox"
	    config.showDebugLog = false // 是否在控制台输出日志，仅调试使用，需要同时设置logger。release版本请设置为 NO
	    config.logNeedEncrypt = true // 是否加密日志，默认加密。release版本请设置为 YES
	    config.autoTrackEnabled = true //是否开启全埋点采集用于圈选功能
      
      // 务必在初始化前设置好代理对象
      BDUGPushService.setNotificationDelegate(**self**)
      let param = BDUGRequestParam()
      param.aId = "Your AppID" //这里的 aid 要与gmp后台通道配置时设置的 push appid一致
      param.channel = "App Store"
      param.appName = "Your AppName"
      param.mainAccountId = "main_account_id" // saas 版本的主账号 id
      param.host = GMPSaaSHost
      // 使用了Notification Service Extension用于UID精准推送及真实到达统计
      // 业务方设置自己App的App Groups中的一个值即可
      BDUGPushService.setAppGroupKey(AppInfo.appGroupKey)
          
			//确保SDK初始化在主线程
      if (!Thread.current.isMainThread) {
		      DispatchQueue.main.async {
		          BDUGPushService.start(with: param)
		          // 如需配置category，创建config参数，不需要配置传nil即可
		          BDUGPushService.registerBDUGPushSDK(with: **nil**)
		      }
      } else {
          BDUGPushService.start(with: param)
          // 如需配置category，创建config参数，不需要配置传nil即可
          BDUGPushService.registerBDUGPushSDK(with: **nil**)
      }

      // 设置应用小红点的数字，-1 即为清空消息
      BDUGPushService.setBadgeNumber(-1)
}
    
@objc func onRegisterSuccess(_ noti: Notification) {
    let did = noti.userInfo?[kBDAutoTrackNotificationRangersDeviceID] ?? ""
    // deviceId installId ssid uuid uuidType 这些请在设备注册完毕之后配置 然后初始化SDK
    BDUGPushService.updateDeviceId(did, ssid: BDAutoTrack.ssID ?? "", uuid: "uuid", uuidType: "uuid type")
}

2.2.3 参数详情

初始化参数列表

id 更新参数列表

其它配置

首先需要在需要初始化的位置引入头文件

#import <BDUGPushSDK/BDUGPushService.h>

接着确保AppDelegate遵循了SDK的两个协议

@interface AppDelegate ()<BDUGPushServiceDelegate,BDUGPushNotificationDelegate>

接入方在调用BDUGPushSDK的初始化接口之前需要做以下几个操作。

1. 自定义通知栏事件的相关配置（也可以不实现，SDK会提供默认的实现），详情可以查看自定义配置部分。

2. 接入方可以配置相关请求参数BDUGRequestParam，并传入相关的参数配置以及接收SDK回调的对象。

如果需要获取SDK初始化结果的回调，以及网络请求的状态，可以实现BDUGPushSDKDelegate中的相关方法，来获取回调时机。

- (void)bdug_pushDidFinishStart:(BDUGBaseResponse *)response;

2.3 Extension 接入示例

需要在 Notification Service Extension target 中接入，如果还未创建 Notification Service Extens 需要先创建对应的 target，在 File -> New -> Target 中选择箭头所指，即可建立扩展

ServiceExtension的NotificationService类，在接收到推送的方法中调用 SDK 的 API

- (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent *contentToDeliver))contentHandler { 
		[BDUGPushExtension defaultManager].hostURLString = @"your host"; // 必传参数，设置域名，scheme依然要保持https，该域名设置的跟主App中host一致即可
    [BDUGPushExtension defaultManager].appGroupKey = @"your appGroupKey"; // 设置App Group中的一个值，要跟主App设置给PushSDK的值保持一致，用于内部同步数据
    [[BDUGPushExtension defaultManager] handleNotificationServiceRequest:request withAttachmentsComplete:^(UNMutableNotificationContent * _Nonnull notificationContent, NSError * _Nonnull error) {
		    // 在这里执行系统contentHandler回调，
		    // 同时将notificationContent作为contentHandler的回传参数
		    contentHandler(content)
		}];
}

override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {
     BDUGPushExtension.defaultManager().hostURLString = "your host" // 必传参数，设置域名，scheme依然要保持https，该域名设置的跟主App中host一致即可
     BDUGPushExtension.defaultManager().appGroupKey = "your appGroupKey" // 设置App Group中的一个值，要跟主App设置给PushSDK的值保持一致，用于内部同步数据

     BDUGPushExtension.defaultManager().handleNotificationServiceRequest(request) { content, error in
						// 在这里执行系统contentHandler回调，
		        // 同时将notificationContent作为contentHandler的回传参数
            contentHandler(content)
     }
 }
    

2.4 自定义数据上报能力

1. 实现 BDUGTrackInterface 协议

#import <BDUGPushSDK/BDUGTrackInterface.h>

@interface BDUGFinderImplement : NSObject <BDUGTrackInterface>

@end
    
@implementation BDUGFinderImplement

- (BOOL)eventV3:(NSString *)event params:(NSDictionary *)params {
		//  在这个方法里对 event 和 params 进行上报
    return [BDAutoTrack eventV3:event params:params];
}

@end

2.初始化 SDK 时赋值将自己实现的数据上报类实例传给 BDUGRequestParam

BDUGRequestParam *param = [BDUGRequestParam requestParam];
param.trackInstance = [BDUGFinderImplement new]; 

2.5 上传推送开关状态

SDK支持宿主向服务端上报目前的App内推送开关状态，0代表打开，1代表关闭（应用内推送开关关闭会导致收不到Push）。
请确保在初始化SDK成功之后调用该接口，否则可能会导致信息上报失败。

+ (void)uploadNotificationStatus:(NSString *)status;

如果你需要调用完上传推送开关的回调，可以在设置回调的类中实现以下方法。

- (void)bdug_pushDidUploadNotificationSwitch:(BDUGBaseResponse *)response;

2.6 处理推送消息

SDK内部收敛了本地和远程推送的相关逻辑，宿主方只需要在初始化时注册了delegate即可收到回调，对于远程推送消息和本地推送消息需要分开处理。SDK只是提供了消息的传递，并不作其它处理，所以具体的消息处理逻辑由宿主自己来实现。

2.6.1 处理远程推送消息

接入方可以通过实现BDUGPushDelegate中的如下方法来实现接收远程推送消息。具体的消息处理相关逻辑交由接入方自己实现。

- (void)bdug_handleRemoteNotification:(BDUGNotificationContent *)content
                withCompletionHandler:(void (^)(void))completionHandler;

2.6.2 处理本地推送消息

接入方可以通过实现BDUGPushDelegate中的如下方法来实现接收本地推送消息。具体的消息处理相关逻辑交由接入方自己实现。

- (void)bdug_handleLocalNotification:(BDUGNotificationContent *)content;

3. apns Payload格式

温馨提示：
payload 中的"extra_str"字段为扩展参数，如果您需要实现点击 Push 吊起 APP 指定页面这种需求可以在扩展参数里读取

payload如下所示：
{
        "aps": {
                "alert": {
                        "body": "Bob wants to play poker", //推送内容
                        "title": "test" //推送标题
                },
                "badge": 10//显示在App左上角的角标数，代表未读消息，需要自己的服务进行统计和控制，apns不支持+1或者-1的操作。
        },
        "extra_str": "{\"push_reward_goods\":1, \"push_reward_page\":2}", //扩展参数，业务方发送时候ClientStr字段放入的jsonString可以透传到此字段，从而传递给客户端
        "rid": 10501// 推送id，客户端上报点击日志的时候，要上报此id， rid+did标记一次推送
}

2.7 登录态变化

如您的产品中有账户体系，请在用户登录后立即设置 uuid，以保证用户登录前后口径一致性。建议通过监听 finder 的注册成功通知，并在回调中调用以下方法去更新 deviceId，ssid，uuid，uuidType，Finder SDK 登陆态变化可参考：Finder SDK 登陆态变化

/**
 更新当前的 设备id，ssid，uuid，uuidType
 
 @param  did 设备ID
 @param  ssid 数说ID，通过 finder sdk（BDAutoTrack） 获取
 @param  uuid 自有账号体系 id
 @param  uuidType 自有账号体系 id 类型，对应 CDP 上的 id code
 */
+ (void)updateDeviceId:(NSString *)did ssid:(NSString *)ssid uuid:(NSString *)uuid uuidType:(NSString *)uuidType;

3. 可选功能

3.1 自定义配置

SDK提供了自定义通知栏事件的配置相关操作，宿主方可以通过BDUGNotificationConfig来初始化相关的配置对象，如果没有设定相关的config，则会使用系统默认的配置逻辑，如果自定义了相关配置，请在初始化SDK时传入配置参数。

+ (void)registerBDUGPushSDKWith:(BDUGNotificationConfig *)config;

具体的配置信息及逻辑关系可以查看头文件BDUGNotificationConfig。

3.2 系统通知权限获取

SDK提供了获取当前App的系统通知权限获取的能力，具体可以使用以下接口来获取相关信息。返回值为“0”或者“1”，1表示已授权，0表示未授权。

+ (NSString *)getSystemPushStatus;

接入方在按照上述步骤完成接入后如果不能正常收到push，请一步步按照下列checklist进行排查，确认接入过程是否有遗漏

• 根据 finderSDK 的接入文档排查 finderSDK 是否正确接入及初始化
• Xcode 工程中是否打开了 Push 权限，以及是否增加了 Notification Service Extension Target
• 是否在gmp后台根据厂商通道开通的信息正确配置各通道
• 是否在应用启动时初始化 Push 及 Finder
• 抓包查看冷启动时是否执行/bytepush/update_sender/接口以及/bytepush/update_token/接口，并查看接口返回信息是否为success，如果不是success则根据使用测试机所属厂商结合厂商推送平台的错误码信息文档进行排查
• 在gmp平台用户触达-触达测试-设备状态查询，选择对应的push应用输入测试机的did，点击查询是否能正确查询到信息如下图所示，测试机的 did 可以通过 BDAutoTrack.rangersDeviceID 获取
  
• 在gmp平台用户触达-触达测试-APP Push进行push的发送测试如下图所示
  

  说明

  如果测试能够正常发送并且对应测试机能够正常接收到push则说明该通道接入成功，由于push涉及多厂商通道，因此接入方请务必对开通的所有厂商通道依次进行测试，避免部分通道未接通但未能在应用上线前排查出问题
  如果接入过程中遇到问题且上述checkList均检查，请联系gmp的rd同学协助解决。

为了更好地排查问题，请先阅读并排查下面的 FAQ，如果仍有问题请飞书联系 gmp 的 rd 同学

1. 无法收到推送看这里

如果无法收到推送，先查看 自己配置的域名下的三个接口上报是否正常，如果不正常请查看下面提供的 checklist 逐步排查问题

• update_sender

• app_notice_status

• update_token

版本记录