Files

T

richjohnrambo e4416da04a fix im server shared database config

2026-09-22 16:45:24 +08:00

10 KiB

Raw Blame History

IM 极光推送前后端对接文档

更新时间：2026-09-IM API → PUT https://api.118im.com/v1/im/devices/2386C7EB-FC30-4849-9FC8-7F2B50229F02/push-token [req=ab961f26-e3a9-4f5f-b0f6-2813b8af3597] 请求体 { "sdk_version": "6.2.0", "push_env": "test", "app_version": "1.0", "token": "1517bfd3f69c6928135", "platform": "ios", "notification_permission": "granted", "provider": "jpush" } IM API ← 成功 PUT https://api.118im.com/v1/im/devices/2386C7EB-FC30-4849-9FC8-7F2B50229F02/push-token [req=ab961f26-e3a9-4f5f-b0f6-2813b8af3597, status=200] 响应体 { "code": 0, "data": { "app_version": "1.0", "device_id": "2386C7EB-FC30-4849-9FC8-7F2B50229F02", "notification_permission": "granted", "platform": "ios", "provider": "jpush", "push_env": "test", "sdk_version": "6.2.0", "updated_at": "2026-09-14T09:49:19.139Z" }, "request_id": "ab961f26-e3a9-4f5f-b0f6-2813b8af3597", "server_time": "2026-09-14T09:49:19.167Z" }04

1. 对接边界

极光 JPush 接入分三段：

边界	责任
客户端和极光 SDK	初始化 SDK、申请通知权限、获取 `registration_id`、绑定 alias、接收和点击 Push。
客户端和 IM Server	登录后上报设备 Push Token，收到 Push 后按 `topic/seq/call_id` 回 IM 拉取补偿。
IM Server 和极光 REST API	保存 `master_secret`，生成 Push 任务，调用 `POST /v3/push`，记录 `msg_id` 和失败原因。

客户端不需要知道 master_secret，也不直接调用极光 REST API。

2. 客户端接入

2.1 SDK 初始化

客户端按平台集成 JPush SDK：

Android：初始化 JPush SDK，创建通知 Channel，按厂商通道要求配置包名、签名、Channel ID。
iOS：配置 APNs 证书或 Token Authentication，申请通知权限。
HarmonyOS：按鸿蒙 SDK 文档初始化并配置通知分类。

客户端启动后取得 registration_id，登录 IM 后调用 IM 后端设备接口上报 Push Token。当前测试环境服务端配置 jpush_use_alias=0，使用 registration_id 投递，不依赖 alias。

device_id 必须稳定，同一台设备不要每次启动变化。切换账号、切换租户、清登录态后必须重新上报 Push Token；客户端本地的上报去重缓存必须按 tenant_code + user_id + device_id + registration_id 隔离，避免设备继续绑定在旧账号上。

如果后续切回 alias 模式，客户端再把 alias 绑定为当前 user_id 的极光安全别名。同一用户多设备允许绑定同一个 alias。

极光 alias 不支持中横线 - 和下划线 _，而 IM user_id 可能包含这两个字符。客户端和后端统一使用以下映射：

jpush_alias = user_id.replace("-", ".").replace("_", "|")

示例：usrd6Ag5opa-ww 对应极光 alias usrd6Ag5opa.ww。

2.2 上报 Push Token

PUT /v1/im/devices/{device_id}/push-token
Authorization: Bearer <IM token>
X-MeetingIM-APIKey: <api_key>
X-IM-Schema: 1
X-Tenant-Code: <tenant_code>
X-Request-ID: <request_id>
Idempotency-Key: <idempotency_key>
Content-Type: application/json

请求：

{
  "provider": "jpush",
  "token": "registration_id",
  "platform": "ios",
  "app_version": "1.0.0",
  "push_env": "test",
  "sdk_version": "5.0.0",
  "notification_permission": "granted"
}

响应 data：

{
  "device_id": "ios_device_1",
  "provider": "jpush",
  "platform": "ios",
  "app_version": "1.0.0",
  "updated_at": "2026-09-04T10:00:00Z"
}

字段说明：

字段	必填	说明
`provider`	是	固定传 `jpush`。后续保留 `fcm`、`apns` 等兼容值。
`token`	是	极光 SDK 返回的 `registration_id`。
`platform`	是	`android`、`ios`、`hmos`。
`app_version`	否	客户端版本，用于排查。
`push_env`	否	`test` 或 `production`，用于 iOS APNs 环境核对。
`sdk_version`	否	JPush SDK 版本。
`notification_permission`	否	`granted`、`denied`、`unknown`。

2.3 点击 Push 后处理

客户端统一读取 extras：

{
  "type": "im_message",
  "tenant_code": "default",
  "topic": "p2p...",
  "seq": "128",
  "sender_id": "usr_sender",
  "message_type": "text"
}

处理规则：

如果未登录，先进入登录或静默登录。
如果租户不一致，先切换到 tenant_code。
按 type 跳转目标页面。
按 topic 和本地游标拉取消息补偿。
按 seq 定位消息；若消息已撤回，展示撤回占位。
对通话类 Push，必须向 IM Server 查询当前通话状态，不能只凭 Push 打开通话中页面。

3. 后端接入

3.1 配置读取

IM Server 从后台配置读取 im_jpush 分组：

{
  "jpush_enabled": "true",
  "jpush_app_key": "app_key",
  "jpush_master_secret": "******",
  "jpush_api_domain": "https://api.jpush.cn",
  "jpush_apns_production": "false",
  "jpush_default_ttl_seconds": "86400",
  "jpush_call_ttl_seconds": "60",
  "jpush_use_alias": "false",
  "jpush_test_model": "false",
  "jpush_classification": "1"
}

测试环境当前使用 registration_id 模式，jpush_use_alias=false。服务端从 im_device_push_tokens 按目标用户查询 provider=jpush 的 token，并调用极光 audience.registration_id。如改为 alias 模式，需要客户端 SDK alias 绑定回调成功，并保持 alias 映射规则一致。

3.2 设备记录

设备表建议至少支持：

字段	说明
`user_id`	IM 用户 ID。
`device_id`	客户端设备 ID。
`provider`	`jpush`。
`push_token`	极光 `registration_id`。
`platform`	`android/ios/hmos`。
`app_version`	App 版本。
`push_env`	`test/production`。
`enabled`	是否有效。
`last_seen_at`	最近上报时间。
`disabled_reason`	禁用原因。

同一 user_id + device_id + provider 覆盖更新；同一 token 换绑账号时，以最后一次登录上报为准并禁用旧绑定。

3.3 Push 任务

服务端生成任务时推荐数据结构：

{
  "task_id": "push_01K...",
  "tenant_code": "default",
  "target_user_id": "usr_target",
  "push_type": "im_message",
  "topic": "p2p...",
  "seq": 128,
  "call_id": "",
  "dedupe_key": "default:usr_target:p2p...:128:im_message",
  "status": "pending",
  "retry_count": 0,
  "next_retry_at": "2026-09-04T10:00:00Z"
}

任务落库或投 Kafka 后由 worker 发送。极光成功返回后记录 msg_id；失败按错误类型重试、跳过或禁用设备。

4. IM Server 调极光

4.1 请求

POST https://api.jpush.cn/v3/push
Authorization: Basic base64(app_key + ":" + master_secret)
Content-Type: application/json

普通消息：

{
  "platform": "ios",
  "audience": {
    "registration_id": ["registration_id_from_jpush"]
  },
  "notification": {
    "ios": {
      "alert": {
        "title": "MeetingIM",
        "body": "你收到一条新消息"
      },
      "sound": "default",
      "badge": "+1",
      "extras": {
        "type": "im_message",
        "tenant_code": "default",
        "topic": "p2p...",
        "seq": "128"
      }
    }
  },
  "options": {
    "time_to_live": 86400,
    "apns_production": false,
    "classification": 1
  }
}

来电提醒：

{
  "platform": "ios",
  "audience": {
    "registration_id": ["registration_id_from_jpush"]
  },
  "notification": {
    "ios": {
      "alert": {
        "title": "视频通话",
        "body": "张三邀请你视频通话"
      },
      "sound": "default",
      "badge": "+1",
      "extras": {
        "type": "call_invite",
        "tenant_code": "default",
        "topic": "p2p...",
        "seq": "30",
        "call_id": "call_01K...",
        "call_type": "video",
        "caller_id": "usr_caller"
      }
    }
  },
  "options": {
    "time_to_live": 60,
    "apns_production": false,
    "classification": 1
  }
}

4.2 响应处理

成功响应示例：

{
  "sendno": "0",
  "msg_id": "18100287008546343"
}