====== 设置离线消息推送 ======

更新时间：2022-07-27

环信 IM 提供离线推送服务，具有低延迟、高交付、高并发、不侵犯用户个人数据的特点，支持你对离线推送功能进行如下配置：

  * 设置推送通知，包含设置推送通知方式和免打扰模式。

  * 设置推送翻译。

===== 技术原理 =====

利用环信即时通讯 IM SDK，可实现以下功能：

  * 设置 app 的推送通知；
  * 获取 app 的推送通知设置；
  * 设置会话的推送通知；
  * 获取一个或多个会话的推送通知设置；
  * 清除会话的推送通知方式的设置；
  * 设置和获取推送通知的首选语言。

===== 前提条件 =====

开始前，请确保满足以下条件：

  * 完成 SDK 初始化，并连接到服务器，详见 [[https://docs-im.easemob.com/ccim/web/quickstart|快速开始]]；
  * 了解环信即时通讯 IM 的使用限制，详见 [[https://docs-im.easemob.com/ccim/limitation|使用限制]]。
  * 你已在环信即时通讯云管理后台中激活推送高级功能。推送高级功能包括设置推送通知模式和免打扰模式。

{{:ccim:web:enable_push_new.png|}}

===== 实现方法 =====

为优化用户在处理大量推送通知时的体验，环信 IM 在应用和会话级别提供了推送通知和免打扰模式的细粒度选项，如下表所示：

<HTML>
<table class='inline table table-striped table-bordered table-hover table-condensed'>
<tr>
<th>
</HTML>
模式
<HTML>
</th>
<th>
</HTML>
选项
<HTML>
</th>
<th>
</HTML>
App
<HTML>
</th>
<th>
</HTML>
会话
<HTML>
</th>
</tr>
<tr>
<td rowspan="3">
</HTML>
推送通知方式
<HTML>
</td>
<td>
</HTML>
ALL：接收所有离线消息的推送通知。
<HTML>
</td>
<td>
</HTML>
✓
<HTML>
</td>
<td>
</HTML>
✓
<HTML>
</td>
<tr>
<td>
</HTML>
AT：只接收提及当前用户的离线消息的推送通知。
<HTML>
</td>
<td>
</HTML>
✓
<HTML>
</td>
<td>
</HTML>
✓
<HTML>
</td>
</tr>
<tr>
<td>
</HTML>
NONE：不接收离线消息的推送通知。
<HTML>
</td>
<td>
</HTML>
✓
<HTML>
</td>
<td>
</HTML>
✓
<HTML>
</td>
</tr>
<tr>
<tr>
<td rowspan="2">
</HTML>
免打扰模式
<HTML>
</td>
<td>
</HTML>
duration：在指定时长内不接收推送通知。
<HTML>
</td>
<td>
</HTML>
✓
<HTML>
</td>
<td>
</HTML>
✓
<HTML>
</td>
<tr>
<td>
</HTML>
startTime & endTime：在指定时间段内不接收推送通知。
<HTML>
</td>
<td>
</HTML>
✓
<HTML>
</td>
<td>
</HTML>
✗
<HTML>
</td>
</tr>
</tr>
</table>
</HTML>
**推送通知方式**

会话级别的推送通知方式设置优先于 app 级别的设置，未设置推送通知方式的会话默认采用 app 的设置。

例如，假设 app 的推送方式设置为 ''%%AT%%''，而指定会话的推送方式设置为''%%ALL%%''。你会收到来自该会话的所有推送通知，而对于其他会话来说，你只会收到提及你的消息的推送通知。

**免打扰模式**

  - 你可以在 app 级别指定免打扰时长和免打扰时间段。环信 IM 在这两个时间段内不发送离线推送通知。
  - 会话仅支持免打扰时长设置；免打扰时间段的设置不生效。

对于 app 和 app 中的所有会话，免打扰模式的设置优先于推送通知方式的设置。

例如，假设在 app 级别指定了免打扰时间段，并将指定会话的推送通知方式设置为 ''%%ALL%%''。免打扰模式与推送通知方式的设置无关，即在指定的免打扰时间段内，你不会收到任何推送通知。

或者，假设为会话指定了免打扰时间段，而 app 没有任何免打扰设置，并且其推送通知方式设置为 ''%%ALL%%''。在指定的免打扰时间段内，你不会收到来自该会话的任何推送通知，而所有其他会话的推送保持不变。

==== 设置 app 的推送通知 ====

你可以调用 ''%%setSilentModeForAll%%'' 方法在 app 级别设置推送通知，并通过指定 ''%%paramType%%'' 字段设置推送通知方式和免打扰模式，如下代码示例所示：

<code javascript>
/**
  options // 推送通知配置选项。
    options: {
    paramType: 0, // 推送通知方式。
    remindType: 'ALL' // 可设置为 `ALL`、`AT` 或 `NONE`。
  }
  options: {
    paramType: 1, // 免打扰时长。
    duration: 7200000 // 免打扰时长，单位为毫秒。
  }
  options: {
    paramType: 2, // 免打扰时间段。
    startTime: {
        hours: 8, // 免打扰时间段的开始时间中的小时数。
        minutes: 0 // 免打扰时间段的开始时间中的分钟数。
    }，
    endTime: {
        hours: 12, // 免打扰时间段的结束时间中的小时数。
        minutes: 0 // 免打扰时间段的结束时间中的分钟数。
    }
  }
*/
const params = {
  options: {
    paramType: 0,
    remindType: 'ALL'
  }
}
WebIM.conn.setSilentModeForAll(params)
</code>

==== 获取 app 的推送通知设置 ====

你可以调用 ''%%getSilentModeForAll%%'' 获取 app 的推送通知设置，示例代码如下：

<code javascript>
// 无需传参数，直接调用。
WebIM.conn.getSilentModeForAll()
</code>

==== 设置单个会话的推送通知 ====

你可以调用 ''%%setSilentModeForConversation%%'' 设置指定会话的推送通知设置，示例代码如下：

<code javascript>
/**
    const params = {
    conversationId: 'test', // 会话 ID：单聊为对方用户 ID，群聊为群组 ID，聊天室会话为聊天室 ID。
    type: 'singleChat', // 会话类型：singleChat（单聊）、groupChat（群聊）和 chatRoom（聊天室）。
    options: {
      paramType: 0, // 推送通知方式。
      remindType: 'ALL' // 可设置为 `ALL`、`AT` 或 `NONE`。
    }
  }
    
    const params = {
    conversationId: '12345567',
    type: 'groupChat',
    options: {
      paramType: 1, // 免打扰时长。
      duration: 7200000 // 免打扰时长，单位为毫秒。
    }
  }
  
  const params = {
    conversationId: '121231233',
    type: 'chatRoom',
    options: {
      paramType: 2, // 免打扰时间段。
      startTime: {
        hours: 8, // 免打扰时间段的开始时间中的小时数。
        minutes: 0 // 免打扰时间段的开始时间中的分钟数。
      }，
      endTime: {
        hours: 12, // 免打扰时间段的结束时间中的小时数。
        minutes: 0 // 免打扰时间段的结束时间中的分钟数。
      }
    }
  }
*/
const params = {
  conversationId: '12345',
  type: 'groupChat',
  options: {
    paramType: 0,
    remindType: 'ALL'
  }
}
WebIM.conn.setSilentModeForConversation(params)
</code>

==== 获取单个会话的推送通知设置 ====

调用 ''%%getSilentModeForConversation%%'' 获取单个会话的推送通知设置，示例代码如下：

<code javascript>
const params = {
  conversationId: 'test', // 会话 ID：单聊为对方用户 ID，群聊为群组 ID，聊天室会话为聊天室 ID。
  type: 'singleChat', // 会话类型：singleChat（单聊）、groupChat（群聊）和 chatRoom（聊天室）。
}
WebIM.conn.getSilentModeForConversation(params)
</code>

==== 获取多个会话的推送通知设置 ====

  - 每次最多可获取 20 个会话的推送通知设置。
  - 如果会话继承了 app 设置或其推送通知设置已过期，则返回的字典不包含此会话。

你可以调用 ''%%getSilentModeForConversations%%'' 获取多个会话的推送通知设置，示例代码如下：

<code javascript>
const params = {
  conversationList: [
    {
      id: 'test', // 会话 ID：单聊为对方用户 ID，群聊为群组 ID，聊天室会话为聊天室 ID。
      type: 'singleChat' // 会话类型：singleChat（单聊）、groupChat（群聊）和 chatRoom（聊天室）。
    },
    {
      id: '1234',
      type: 'groupChat'
    }
  ]
}
WebIM.conn.getSilentModeForConversations(params)
</code>

==== 清除单个会话的推送通知方式的设置 ====

你可以调用 ''%%clearRemindTypeForConversation%%'' 方法清除指定会话的推送通知方式的设置。清除后，默认情况下，此会话会继承 app 的设置。

示例代码如下：

<code javascript>
const params = {
  conversationId: '12345', // 会话 ID：单聊为对方用户 ID，群聊为群组 ID，聊天室会话为聊天室 ID。
  type: 'groupChat', // 会话类型：singleChat（单聊）、groupChat（群聊）或 chatRoom（聊天室）。
}
WebIM.conn.clearRemindTypeForConversation(params)
</code>

==== 设置推送翻译 ====

如果用户启用[[https://docs-im.easemob.com/ccim/web/translation#%E5%8F%91%E6%B6%88%E6%81%AF%E6%97%B6%E8%87%AA%E5%8A%A8%E7%BF%BB%E8%AF%91|自动翻译]]功能并发送消息，SDK 会同时发送原始消息和翻译后的消息。

推送通知与翻译功能协同工作。作为接收方，你可以设置你在离线时希望接收的推送通知的首选语言。如果翻译消息的语言符合你的设置，则翻译消息显示在推送通知中；否则，将显示原始消息。

你可以调用 ''%%setPushPerformLanguage%%'' 设置推送通知的首选语言，示例代码如下：

<code javascript>
/**
    language: string, // 推送通知的首选语言。
*/
const params = {
  language: 'EU'
}
WebIM.conn.setPushPerformLanguage(params)
</code>

你可以调用 ''%%getPushPerformLanguage%%'' 获取推送通知的首选语言，示例代码如下：

<code javascript>
WebIM.conn.getPushPerformLanguage() // 无需传参数，直接调用。
</code>
模式	选项	App	会话
推送通知方式	ALL：接收所有离线消息的推送通知。	✓	✓
	AT：只接收提及当前用户的离线消息的推送通知。	✓	✓
	NONE：不接收离线消息的推送通知。	✓	✓
免打扰模式	duration：在指定时长内不接收推送通知。	✓	✓
免打扰模式	startTime & endTime：在指定时间段内不接收推送通知。	✓	✗