推送令牌登记

deviceToken 由 APNs 生成，会随重装、恢复备份、系统更新而变化；每次拿到新 token 都应调用 IMLib 的推送令牌接口登记。IMLib 维护用户 × 平台 × token 的台账，服务端据此投递离线推送。

能力​

登记时机​

• 拿到 deviceToken 后立即登记（`didRegisterForRemoteNotificationsWithDeviceToken`）。
• 登录成功、切换账号后重新登记：token 属于设备，但台账按用户隔离。
• App 升级后如果 token 变化，重新登记；旧 token 由服务端按换绑规则置为失效。
• 退出登录时注销当前设备的 token，避免下一个账号收到上一个账号的推送。

令牌生命周期​

registerPushToken​

注册设备推送 token（IDL rev21 C23 收口；客户端 REST `POST /api/apps/{appkey}/push/tokens`，服务端 rev20 已实现，本 op 补 SDK 语义面）→ PushToken。幂等键 `(userId, platform, token)`：重复注册返回既有 tokenId 并重新置 active=true；`token` 8..=512 字符、`platform` ∈ ios|android|web|huawei|xiaomi|oppo|vivo|fcm、未知平台/长度非法 1001、每用户 20 个活跃 token 上限（超限 1001）、注销/封禁用户 1016；同一 (platform, token) 被其它用户注册时旧记录置 active=false（设备换绑）。

参数​

返回​

PushToken：成功返回的数据；失败时按错误码处理

示例（Swift / Objective-C）​

let deviceToken = "TOKEN"
let tokenPush = await client.registerPushToken(options: IMPRegisterPushTokenOptions(platform: "ios", token: deviceToken))
print(tokenPush.code)

[client registerPushTokenWithOptions:@{ @"platform": @"ios", @"token": @"TOKEN", @"deviceId": @"dev_1001", @"appVersion": @"1.0.0" } completion:^(IMPOSResult *result) {
    if (result.code != 0) { NSLog(@"IM 调用失败：%ld %@", (long)result.code, result.msg); }
}];

getPushTokens​

查询本人设备推送 token（IDL rev21 C23；客户端 REST `GET /api/apps/{appkey}/push/tokens`）→ `{userId,tokens:[PushToken],total,activeTotal,platforms}`；含 active=false 历史，按 createdAt 倒序。只读、幂等、不产生事件。

参数​

返回​

{userId:string, tokens:PushToken[], total:uint32, activeTotal:uint32, platforms:string[]}：成功返回的数据；失败时按错误码处理

示例（Swift / Objective-C）​

let tokens = await client.getPushTokens()
print(tokens.code)

[client getPushTokensWithCompletion:^(IMPOSResult *result) {
    if (result.code != 0) { NSLog(@"IM 调用失败：%ld %@", (long)result.code, result.msg); }
}];

unregisterPushToken​

注销本人设备推送 token（IDL rev21 C23；客户端 REST `DELETE /api/apps/{appkey}/push/tokens/{tokenId}`）：软删除 active=false 并保留历史供审计 → `{tokenId,userId,platform,deleted,active:false,alreadyInactive}`。非本人或不存在 1001（不泄露他人 token）；重复注销幂等成功（alreadyInactive=true）。

参数​

返回​

{tokenId:string, userId:string, platform:string, deleted:bool, active:bool, alreadyInactive:bool}：成功返回的数据；失败时按错误码处理

示例（Swift / Objective-C）​

let removed = await client.unregisterPushToken(tokenId: "pt_1001")
print(removed.code)

[client unregisterPushTokenWithTokenId:@"pt_1001" completion:^(IMPOSResult *result) {
    if (result.code != 0) { NSLog(@"IM 调用失败：%ld %@", (long)result.code, result.msg); }
}];

端到端示例​

let refresh = await client.registerPushToken(options: IMPRegisterPushTokenOptions(platform: "ios", token: "TOKEN2"))
print(refresh.code)