MSDK WIKI

概述

推送功能可以实现在游戏未运行的情况下给玩家手机推送游戏相关的信息，如各种节假日活动、周年庆活动等。推送效果如下图所示：

显示详情

接入向导

Step1 前置条件

1) 您已经在info.plist中配置推送开关，如下图所示：

2) 使用Xcode8编译的业务需注意打开工程的TARGETS->Capabilities->Push Notificatons推送开关，如下图所示：

3) MSDK iOS推送依赖苹果APNS实现，需要各业务PM或腾讯侧接口人在腾讯内网KeyStore、飞鹰系统上配置相关证书。

Step2 iOS配置证书

配置证书仅针对iOS端，Android端可忽略该项。

1 申请证书

2 制作SSL证书

3 上传SSL证书

1 申请证书

产品需在KeyStore(腾讯内网，需业务PM或腾讯侧接口人操作)申请推送和发布证书，具体事宜详询KeyStore-helper(证书助手)。

2 制作SSL证书

1)从KeyStore(腾讯内网，需业务PM或腾讯侧接口人操作)上下载P12证书，具体路径：游戏产品->发布管理->证书管理，以MSDK为例如下图所示：

2)在打开的界面中下载发布证书下的xxx_push.p12文件

3)打开终端进入到xxx_push.p12文件所在的目录执行以下命令：

//该命令生成的pem证书无密码，上传至飞鹰系统时无需填写密码，注意和p12证书密码的区分
openssl pkcs12 -in xxx_push.p12 -out xxx_push.pem -nodes

3 上传SSL证书

1)进入飞鹰系统(腾讯内网，需业务PM或腾讯侧接口人操作)，点击左侧导航栏：MSDK接入->腾讯移动推送->苹果平台->证书配置，如下图所示：

上传步骤2 制作SSL证书中生成的pem证书至生产环境，密码无需填写。上传成功后点击左上角 更新游戏证书信息 按钮保存。开发环境证书无需理会，至此，证书已设置完成。

Step3 添加推送相关代码

OC接口和C++接口二选一使用

1 以下接口为OC接口

您还需要在AppDelegate.mm中添加推送相关的5个方法：

1) 注册推送

签名文件配置正确才能成功注册推送。游戏需要在didFinishLaunchingWithOptions方法中调用MSDK的WGRegisterAPNSPushNotification方法进行推送注册。代码示例：

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    …
    [MSDKXG WGRegisterAPNSPushNotification:launchOptions];
    …
}

2) 注册成功

注册成功游戏会收到didRegisterForRemoteNotificationsWithDeviceToken回调方法，游戏需要在此方法中调用WGSuccessedRegisterdAPNSWithToken方法将deviceToken上报到MSDK。代码示例：

-(void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken
{
  [MSDKXG WGSuccessedRegisterdAPNSWithToken:deviceToken];
}

3) 注册失败

注册失败游戏会收到didFailToRegisterForRemoteNotificationsWithError方法回调，游戏需要调用WGFailedRegisteredAPNS方法通知MSDK注册推送失败。示例代码：

-(void)application:(UIApplication *)application didFailToRegisterForRemoteNotificationsWithError:(NSError *)error
{
  [MSDKXG WGFailedRegisteredAPNS];
}

4) 接收消息

成功注册推送后，应用收到推送消息会进入didReceiveRemoteNotification方法。游戏需要在此方法中调用WGReceivedMSGFromAPNSWithDict方法，将推送消息给MSDK做解析，解析结果通知给游戏。示例代码：

-(void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo
{
  [MSDKXG WGReceivedMSGFromAPNSWithDict:userInfo];
}

5) 清空badge

应用需要在applicationDidBecomeActive中调用WGCleanBadgeNumber方法将应用桌面图标右上角的推送条目清空。示例代码：

-(void)applicationDidBecomeActive:(UIApplication *)application
{
  [MSDKXG WGCleanBadgeNumber];
}

2 以下接口为C++接口

您还需要在AppDelegate.mm中添加推送相关的5个方法：

1) 注册推送

功能描述

注册消息推送，签名文件配置正确才能成功注册推送。游戏需要在didFinishLaunchingWithOptions方法中调用MSDK的WGRegisterAPNSPushNotification方法进行推送注册。

接口声明

void WGRegisterAPNSPushNotification(unsigned char *launchOptions);

参数说明

参数名称	类型	说明
launchOptions	unsigned char*	"-application:didFinishLaunchingWithOptions:"中的(NSDictionary *)launchOptions参数转换为json字符串

2) 注册成功

功能描述

注册成功游戏会收到didRegisterForRemoteNotificationsWithDeviceToken回调方法，游戏需要在此方法中调用WGSuccessedRegisterdAPNSWithToken方法将deviceToken上报到MSDK。

接口声明

void WGSuccessedRegisterdAPNSWithToken(unsigned char *deviceToken);

参数说明

参数名称	类型	说明
deviceToken	unsigned char*	"-application:didRegisterForRemoteNotificationsWithDeviceToken:"中的(NSData *)deviceToken参数转换为字符串

3) 注册失败

功能描述

注册失败游戏会收到didFailToRegisterForRemoteNotificationsWithError方法回调，游戏需要调用WGFailedRegisteredAPNS方法通知MSDK注册推送失败。

接口声明

void WGFailedRegisteredAPNS();

参数说明

无

4) 接收消息

功能描述

成功注册推送后，应用收到推送消息会进入didReceiveRemoteNotification方法。游戏需要在此方法中调用WGReceivedMSGFromAPNS方法，将推送消息给MSDK做解析，解析结果通知给游戏。

接口声明

void WGReceivedMSGFromAPNS(unsigned char *userInfo);

参数说明

参数名称	类型	说明
userInfo	unsigned char*	"-application:didReceiveRemoteNotification:"中的(NSDictionary *)userInfo参数转换为json字符串

5) 清空badge

功能描述

应用需要在applicationDidBecomeActive中调用WGCleanBadgeNumber方法将应用桌面图标右上角的推送条目清空。

接口声明

void WGCleanBadgeNumber();

参数说明

无

腾讯移动推送 TPNS

腾讯移动推送为收费版本。接入需要重新申请accessId和accessKey。MSDKV3客户端从3.3.12版本开始集成腾讯移动推送，目前支持可插件化接入。

1 申请accessId和accessKey

accessId和accessKey可直接在飞鹰系统（内网访问）注册申请，需联系MSDK助手协助注册

若该游戏已在腾讯云管理端注册腾讯云账号且已有腾讯移动推送账号，也可迁移到飞鹰系统，需联系MSDK助手协助迁移

在飞鹰系统注册申请或迁移到飞鹰系统，均需要业务提供UIN（可登录腾讯云官网查看UIN：https://console.cloud.tencent.com/developer
公司内部用户可以使用腾讯云内部账号购买，公司内部账号查询方法和申请方法详见 https://docs.qq.com/doc/DVWZBYkJ2SHBaUE9y

2 客户端接入说明

由于数据上报能力腾讯移动推送侧为反射调用，因此需要各业务自行添加对腾讯移动推送的依赖。接入推送能力除添加MSDKPush/MSDKPush.framework外还需添加MSDKPush/XG目录下的腾讯移动推送库及头文件。

2.1 向info.plist中添加配置

腾讯移动推送需要配置 accessId 和 accessKey 信息。accessId和accessKey请配置到info.plist，其中，accessId为Number类型，accessKey为字符串类型。配置示例如下：

    <key>XG_V2_ACCESS_ID</key>
    <integer>xxx</integer>
    <key>XG_V2_ACCESS_KEY</key>
    <string>xxx</string>

如果接入点为上海集群，需要处理以下配置

在项目工程的 info.plist 添加

<!-- 3.3.15及之前版本配置 -->
<key>XG_HOST</key>
<string>https://guid.tpns.sh.tencent.com</string>
<key>XG_PORT</key>
<integer>0</integer>
<key>XG_STAT_HOST</key>
<string>https://stat.tpns.sh.tencent.com</string>
<key>XG_STAT_PORT</key>
<integer>0</integer>

<!-- 3.3.16版本配置 -->
<key>XG_HOST</key>
<string>https://api.tpns.sh.tencent.com</string>
<key>XG_PORT</key>
<integer>0</integer>
<key>XG_STAT_HOST</key>
<string>https://stat.tpns.sh.tencent.com</string>
<key>XG_STAT_PORT</key>
<integer>0</integer>

<!-- 3.3.17及以上版本配置 -->
<key>XG_HOST</key>
<string>tpns.sh.tencent.com</string>

XG_HOST 和 XG_STAT_HOST 需要带 https 头
3.3.16 版本 XG_HOST 需要修改为 https://api.tpns.sh.tencent.com
3.3.17 版本开始需要删除 XG_PORT、XG_STAT_HOST、XG_STAT_PORT 配置，并将 XG_HOST 修改为 tpns.sh.tencent.com （注意：不需要带 https 头）

2.2 注销信鸽免费版本

注销方式是在info.plist中配置信鸽免费版本的accessId。请在info.plist中添加XG_FREE_ACCESS_ID配置，类型为Number。相应的Key和配置示例如下：

    <key>XG_FREE_ACCESS_ID</key>
    <integer>xxx</integer>

其中，XG_FREE_ACCESS_ID 填写升级腾讯移动推送版本前免费版本信鸽的accessId，如果不知道，可以在飞鹰系统SDK参数处查询。

2.3 删除腾讯移动推送

如果不接入腾讯移动推送，需要修改并删除以下内容，如下：

info.plist中将MSDK_PUSH_SWITCH设置为false
将2.1、2.2中的腾讯移动推送配置删除
删除MSDKPush.framwork

注意事项

如果希望游戏在前台时仍可收到推送，则需要在info.plist文件中配置 MSDK_PUSH_AT_FOREGROUND 为 true，该配置默认为关闭。

3 管理端配置说明

3.1 创建产品和应用

创建产品和应用，详情参考：腾讯移动推送-创建产品和应用文档

3.2 申请试用

点击页面中【申请试用/测试】，企业名称统一填写“腾讯”，联系电话&邮箱可按填写人信息录入，申请后可联系MSDK助手对接激活试用。

3.3 iOS 证书配置

证书配置方法，详情参考：腾讯移动推送-上传推送证书方法文档

3.4 创建推送任务及推送测试方法

创建推送任务及推送测试方法，详情参考：腾讯移动推送-创建推送任务及推送测试方法文档

4 腾讯移动推送服务付费说明

付费说明，详情参考：付费说明文档

接口人：腾讯云助手(cloud IT support)

5 通知服务扩展插件配置（统计抵达必备插件）

MSDK 仅携带 TPNS 扩展库，需要游戏业务集成接入，具体接入请参考 TPNS 指引文档：通知服务扩展的使用说明

接口人：腾讯云助手(cloud IT support)

MSDK V3.3.15 及以后版本新增以下接口

1 账号绑定

1)功能描述

开发者可以针对不同的用户绑定自定义账号，然后对该账号进行推送，账号不能为空。单个应用最多可以有10000个自定义标签/账号，每个设备token最多可绑定100个自定义标签/账号。

这里的账号可以是邮箱、QQ 号、手机号、用户名等任意类别的业务账号
同一个账号绑定多个设备时，后台将默认推送消息到最后绑定的设备

2)接口声明

声明及相关参数说明可在WGPlatform.h文件中查看

void WGSetPushAccount(unsigned char *account);

3)参数说明

参数名称	类型	说明
account	unsigned char *	账号

4)示例代码

WGPlatform::GetInstance()->WGSetPushAccount("account");

2 解除账号绑定

1)功能描述

对已绑定的自定义账号进行解绑，账号不能为空。

账号解绑只是解除 Token 与 App 账号的关联，若使用全量/标签/Token 推送仍然能收到通知/消息

2)接口声明

声明及相关参数说明可在WGPlatform.h文件中查看

void WGDeletePushAccount(unsigned char *account);

3)参数说明

参数名称	类型	说明
account	unsigned char *	账号

4)示例代码

WGPlatform::GetInstance()->WGDeletePushAccount("account");

3 反注册

1)功能描述

当用户已退出或 App 被关闭，不再需要接收推送时，可以取消注册 App，即反注册。（一旦设备反注册，直到这个设备重新注册成功期间内，下发的消息该设备都无法收到）。如再次需要消息推送，则必须再次调用 WGRegisterAPNSPushNotification 方法重启腾讯移动推送服务。

反注册操作切勿过于频繁，可能会造成后台同步延时
切换账号无需反注册，多次注册自动会以最后一次为准

2)接口声明

声明及相关参数说明可在WGPlatform.h文件中查看

void WGUnregisterPush();

3)参数说明

无

4)示例代码

WGPlatform::GetInstance()->WGUnregisterPush();

发送推送消息

进入飞鹰系统(腾讯内网，需业务PM或腾讯侧接口人操作)，点击左侧导航栏：MSDK接入->腾讯移动推送(无权限的可内网联系MSDK助手对接)，进入页面配置即可，如下图所示：

注意：

测试推送消息时切忌勿全量推送，可使用单个账号或者批量账号测试，以免全网用户收到测试的推送消息。

添加本地推送

除了远程推送外，游戏还可进行本地消息推送，例如体力恢复提醒的场景。

1 iOS本地推送

功能描述

本地推送是相对于远程推送而言，无需同远程服务器交互在本地就可完成的消息通知，主要应用于体力恢复提醒等场景。

接口声明

long WGAddLocalNotification(LocalMessage &localMessage);

参数说明

参数名称	类型	说明
localMessage	LocalMessage 类	跳转查看

返回值

1 添加成功，0 添加失败

示例代码

//若当前时间为2015-09-17 17:00:00，十秒钟后推送
LocalMessage message;
message.fireDate = "2015-09-17 17:00:10";
message.alertBody = "Local Notification";
message.badge = 1;
message.alertAction = "Start";
KVPair item;
item.key = "key";
item.value = "vlaue";
std::vector<KVPair> userInfo;
userInfo.push_back(item);
message.userInfo = userInfo;
WGPlatform::GetInstance()->WGAddLocalNotification(message);

特殊说明

1) 该接口需游戏退到后台或进程被杀后才可收到本地推送。

2) 用户点击本地推送拉起游戏，游戏若需要根据不同的推送采取不同的处理策略需在AppController(UnityAppController)实现如下代理方法:

- (void)application:(UIApplication *)application didReceiveLocalNotification:(UILocalNotification *)notification
{
    // 处理推送消息
    NSLog(@"收到本地推送消息:%@ %@",notification.alertBody,notification.userInfo);
    LocalMessage message;
    message.alertBody = [notification.alertBody cStringUsingEncoding:NSUTF8StringEncoding];
    std::vector<KVPair> userInfo;
    for (NSString *key in notification.userInfo.allKeys)
    {
        NSString *value = notification.userInfo[key];
        KVPair item;
        item.key = [key cStringUsingEncoding:NSUTF8StringEncoding];
        item.value = [value cStringUsingEncoding:NSUTF8StringEncoding];
        userInfo.push_back(item);
    }
    message.userInfo = userInfo;
    //游戏可根据该message做出不同的策略。
}

名词解释

无

2 添加本地前台推送

功能描述

默认本地推送游戏在前台运行时不会进行弹窗，通过 WGAddLocalNotificationAtFront 接口可实现指定的推送弹窗。

接口声明

long WGAddLocalNotificationAtFront(LocalMessage &localMessage);

参数说明

参数名称	类型	说明
localMessage	LocalMessage 类	跳转查看

示例代码

LocalMessage message;    
message.alertBody = "Local Notification At Front";
message.userInfoKey = "FrontKey";
message.userInfoValue = "FrontValue";
WGPlatform::GetInstance()->WGAddLocalNotificationAtFront(message);

特殊说明

该接口无需设置推送时间，调用完接口立马展示且无法被撤销。

名词解释

无

3 清除未生效本地推送

功能描述

可以使用 WGClearLocalNotification 接口清除还未生效的本地推送。

接口声明

void WGClearLocalNotification(LocalMessage &localMessage);

参数说明

参数名称	类型	说明
localMessage	LocalMessage 类	跳转查看

示例代码

LocalMessage message;
//注：此处的userInfoKey、userInfoValue需和添加推送时的保持一致，否则无法撤销
message.userInfoKey = "key";
message.userInfoValue = "value";
WGPlatform::GetInstance()->WGClearLocalNotification(message);

特殊说明

无

名词解释

无

4 清除所有本地推送

功能描述

使用 WGClearLocalNotifications 接口可清空所有本地推送。

接口声明

void WGClearLocalNotifications();

参数说明

无

示例代码

WGPlatform::GetInstance()->WGClearLocalNotifications();

特殊说明

无

名词解释

无

标签推送

游戏可以针对用户设置标签，如性别、年龄、学历、爱好等，另SDK中预置的有默认标签，推送时可根据不同的标签有针对的进行推送。

1 预置标签

目前腾讯移动推送提供以下三类预置标签，游戏无需另外设置：

地理位置(省一级)
应用版本号
流失用户(3天or7天)

2 设置标签

功能描述

游戏可以针对不同的用户设置标签，一款游戏最多共可设置10000个标签，每个用户在某一款游戏下最多可设置100个标签，设置标签时注意标签中不可包含空格。

接口声明

void WGSetPushTag(unsigned char* tag);

参数说明

参数名称	类型	说明
tag	unsigned char*	不能为null或包含空格

返回值

无

示例代码：

WGPlatform::GetInstance()->WGSetPushTag((unsigned char*)"Student");

特殊说明

无

名词解释

无

3 删除标签

功能描述

删除所设置的用户标签，推送时此用户将无法接收到此标签下的推送消息。

接口声明

void WGDeletePushTag(unsigned char* tag);

参数说明

参数名称	类型	说明
tag	unsigned char*	不能为null或包含空格

返回值

无

示例代码

WGPlatform::GetInstance()->WGDeletePushTag((unsigned char*)"Student");

特殊说明

无

名词解释

无

4 发送标签推送消息

发送标签推送消息同发送推送消息一样，只是在添加推送消息时“推送目标”需选择标签，如下图所示：

点击推送消息回调

1)功能描述

提供 TPNS 推送点击回调 `OnReceiveNotificationResponseNotify`，可通过回调获取 userInfo 字段转化后的 json 字符串。3.3.26 版本开始新增该接口。

2)示例代码


//设置回调
MyObserver* ob = MyObserver::GetInstance();
WGPlatform::GetInstance()->WGSetObserver(ob);

//回调示例
void MyObserver::OnReceiveNotificationResponseNotify(const char *userInfo)
{
	...
}

常见问题

信鸽免费版本升级到腾讯移动推送版本需删除以下内容

信鸽免费版本升级到腾讯移动推送版本存在旧版本文件、配置需要清理。iOS端信鸽免费版直接集成到了MSDK的framework中，只需要替换旧的MSDK Framework就能够实现升级，不需要删除额外文件。iOS端腾讯移动推送版本采用了插件化，注意添加相应的framework。