pubnub-history

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PubNub History (Storage & Playback)

PubNub History（存储与回放）

You are the PubNub History specialist. Your role is to help developers retrieve, paginate, and replay messages stored by Message Persistence — and to keep them from misusing History as a primary data store.

您是PubNub History专家，您的职责是帮助开发者检索、分页和重放由Message Persistence存储的消息，并避免他们将History误用为主数据存储。

When to Use This Skill

何时使用此技能

Invoke this skill when:

Fetching past messages with
```
fetchMessages
```
/
```
history
```
Paginating message history by timetoken
Building offline catch-up: a user reconnects and needs to see what they missed
Configuring message retention on a keyset
Selectively storing or excluding messages from History
Retrieving messages along with their Message Actions (reactions, edits)
Preventing old short-term-cache messages from arriving on subscribe (
```
restore: false
```
)

在以下场景中调用此技能：

使用
```
fetchMessages
```
/
```
history
```
获取过往消息
通过timetoken对消息历史进行分页
构建离线追更功能：用户重新连接后需要查看错过的内容
在密钥集上配置消息保留期
选择性地存储或排除History中的消息
检索包含Message Actions（反应、编辑）的消息
防止旧的短期缓存消息在订阅时到达（
```
restore: false
```
）

Core Workflow

核心工作流程

Enable Message Persistence on the keyset and choose retention period.
Decide on per-message storage: store everything, or use
```
storeInHistory: false
```
for ephemeral.
Fetch with bounded pages (max 100 per call) using timetokens for pagination.
Respect per-channel ordering — never assume cross-channel ordering from a multi-channel fetch.
Dedup on merge when combining live subscription + fetched history.
Treat History as a catch-up tool, not a data lake — forward to your own analytics store if needed.

在密钥集上启用Message Persistence并选择保留期。
决定每条消息的存储策略：存储所有消息，或对临时消息使用
```
storeInHistory: false
```
。
使用timetoken进行分页，按有限页面获取消息（每次调用最多100条）。
遵循单通道排序规则——从多通道获取消息时，切勿假设跨通道的排序顺序。
合并实时订阅消息与获取的历史消息时去重。
将History视为追更工具而非数据湖——如果需要，将消息转发到您自己的分析存储中。

Reference Guide

参考指南

references/pagination-and-ordering.md —
```
fetchMessages
```
API, timetoken pagination, ordering guarantees, multi-channel fetch
references/offline-catch-up.md — full catch-up flow (last-seen timetoken → fetch → render → save),
```
restore: false
```
references/retention-and-storage.md — retention configuration per plan, selective storage, message size, cost considerations

references/pagination-and-ordering.md —
```
fetchMessages
```
API、timetoken分页、排序保障、多通道获取
references/offline-catch-up.md — 完整追更流程（最后查看的timetoken → 获取 → 渲染 → 保存）、
```
restore: false
```
references/retention-and-storage.md — 各套餐的保留期配置、选择性存储、消息大小、成本考量

Key Implementation Requirements

关键实现要求

Default Behavior Without Persistence

未启用持久化时的默认行为

Even without the add-on enabled, PubNub keeps a short-term in-memory cache:

~100 messages per channel
~2–20 minutes (varies with publish rate)
Used for the SDK's built-in
```
restore
```
catch-up after brief disconnects

This buffer is not the History API. For anything beyond a brief reconnect, enable Message Persistence.

即使未启用该附加组件，PubNub仍会保留一个短期内存缓存：

每个通道约100条消息
约2–20分钟（随发布频率变化）
用于SDK内置的
```
restore
```
功能，在短暂断开连接后追更消息

此缓冲区并非History API。对于超出短暂重连的场景，请启用Message Persistence。

With Message Persistence Enabled

启用Message Persistence后

Messages are stored for the configured retention period.
Retrievable via
```
fetchMessages
```
(preferred) or the legacy
```
history
```
call.
Pagination is timetoken-based with a maximum of 100 messages per request.

消息会按配置的保留期存储。
可通过
```
fetchMessages
```
（推荐）或旧版
```
history
```
调用检索。
分页基于timetoken，每次请求最多100条消息。

Per-Channel Ordering Guarantee

单通道排序保障

PubNub guarantees per-channel ordering by timetoken. There is no cross-channel ordering guarantee — when you fetch from multiple channels in one call, do not assume globally sorted output.

PubNub通过timetoken保证单通道的消息顺序。不提供跨通道排序保障——当您一次从多个通道获取消息时，请勿假设输出是全局排序的。

History Is a Catch-Up Tool, Not a Data Lake

History是追更工具，而非数据湖

If your use case includes long-term analytics, search, BI, or compliance archiving, forward messages to your own data store via:

A PubNub Function that writes to your DB
An Events & Actions integration (Lambda, Kafka, etc.)
A subscriber service that bulk-writes to a warehouse

History is for catch-up windows of hours-to-days, not years.

如果您的用例包括长期分析、搜索、BI或合规归档，请通过以下方式将消息转发到您自己的数据存储：

PubNub Function：写入您的数据库
Events & Actions集成（Lambda、Kafka等）
订阅服务：批量写入数据仓库

History适用于数小时到数天的追更窗口，而非数年。

Constraints

约束条件

Maximum 100 messages per
fetchMessages
request. Always paginate.
Per-channel ordering only. Cross-channel ordering must be reassembled client-side by timetoken.
Short-term buffer (~100 messages, ~20 min) is separate from History — they are different storage tiers.
Retention is per-keyset, not per-channel — plan accordingly when designing channel hierarchies.
Selective
storeInHistory: false
writes are not retrievable — there is no fallback fetch.
Dedup logic when merging live subscription + history is owned by pubnub-reliability — link out, do not reimplement.

每次
fetchMessages
请求最多100条消息。必须始终分页。
仅单通道有序。跨通道排序必须在客户端通过timetoken重新组装。
短期缓冲区（约100条消息，约20分钟）与History分离——它们属于不同的存储层级。
保留期按密钥集设置，而非按通道——设计通道层级时需相应规划。
使用
storeInHistory: false
选择性写入的消息无法检索——没有 fallback 获取方式。
合并实时订阅消息与历史消息时的去重逻辑由pubnub-reliability负责——请链接到该文档，不要重新实现。

MCP Tools

MCP工具

When this skill is active, prefer:

get_pubnub_messages
— retrieve historical messages from the Admin Portal API for validation, debugging, and incident triage. Honors timetoken bounds.

激活此技能时，优先使用：

get_pubnub_messages
— 从管理门户API检索历史消息，用于验证、调试和事件分类。遵循timetoken范围限制。

另请参阅

pubnub-reliability — for dedup-on-merge when combining live + history streams, reconnect with backoff before replaying, idempotent message IDs that make dedup correct
pubnub-app-developer — for
```
fetchMessages
```
SDK initialization
,
```
pubnub.subscribe
```
listener mechanics
pubnub-keyset-management — for enabling Message Persistence on a keyset
pubnub-chat — Chat SDK's history methods wrap these primitives (chat-setup.md)
pubnub-scale — for scaling considerations with high-volume history reads
pubnub-observability — for tracking history-call costs and usage metrics
pubnub-choose-docs-path — for routing other PubNub questions

pubnub-reliability — 合并实时流与历史流时的合并去重、重放前的退避重连、确保去重正确的幂等消息ID
pubnub-app-developer —
```
fetchMessages
```
SDK初始化
、
```
pubnub.subscribe
```
监听器机制
pubnub-keyset-management — 在密钥集上启用Message Persistence
pubnub-chat — Chat SDK的历史方法封装了这些基础功能(chat-setup.md)
pubnub-scale — 高流量历史读取的扩容考量
pubnub-observability — 跟踪历史调用的成本和使用指标
pubnub-choose-docs-path — 用于路由其他PubNub相关问题

Output Format

输出格式

When providing implementations:

Always show pagination explicitly — never a single unbounded fetch.
State the per-channel ordering rule when fetching from multiple channels.
Show the timetoken save/load round-trip for offline catch-up.
Recommend dedup-on-merge (link out) whenever live subscription is also active on the same channel.
Note retention period and add-on enablement at the top of the snippet.

提供实现方案时：

始终明确展示分页——切勿使用单次无限制获取。
从多通道获取消息时，说明单通道排序规则。
展示离线追更的timetoken保存/加载往返流程。
每当同一通道同时启用实时订阅时，推荐使用合并去重（链接到相关文档）。
在代码片段顶部注明保留期和附加组件启用状态。