bitrix-pull

リアルタイムプル（pull）

基準：main 23.0+ · 検証済み：pull 26.100.0、main 26.800.0

pull は、プッシュサーバーを通じてブラウザーとモバイルアプリに短いコマンドを配信します。サーバーが設定されている必要があります（CPullOptions::GetQueueServerStatus()）。モバイルプッシュには CPullOptions::GetPushStatus() も必要です。

仕組み	用途
Pull	即時の UI 通知：「行 42 が変更されました」、カウンター
Messenger / agents（bitrix-background-jobs）	リトライを伴う永続的な処理。UI の更新が必要な場合は、ワーカーから Pull を送信します

PHP から送信する

\Bitrix\Main\Loader::includeModule('pull');

$ok = \Bitrix\Pull\Event::add([$userId, $otherUserId], [
    'module_id' => 'vendor.module',   // lower-cased by the kernel
    'command' => 'itemUpdated',
    'params' => ['id' => $itemId],   // IDs and flags only; load data via AJAX afterwards
    // 'expiry' => 86400,            // seconds, default
]);
if (!$ok) {
    $error = \Bitrix\Pull\Event::getLastError();
}

• 受信者：ユーザー ID、32 文字のチャンネル ID、または Bitrix\Pull\Model\Channel。第 3 引数は \CPullChannel::TYPE_PRIVATE（デフォルト）または TYPE_SHARED です。
• ユーザーごとのパラメーター：'user_params' => [$userId => ['unread' => 3]]（そのユーザーの params にマージ）、'dictionary' => [...]（全員にマージ）。結果の信頼性が保証されるのは pull 26.100 以降です。それ以前は、これらのキーに対する偽の結果は失敗を意味しません。getLastError() を確認してください。
• ペイロードのどこかに無効な UTF-8 が含まれていると、false が返されます（EVENT_BAD_ENCODING）。
• 配信はキューに登録され、リクエストの終了時にバックグラウンドジョブによって送信されます。長時間実行する CLI ワーカーでは、add() の直後に \Bitrix\Pull\Event::send() を呼び出してください。

タグ（CPullWatch）

\CPullWatch::Add($userId, 'VENDOR_ITEM_' . $itemId);          // when rendering the page
\CPullWatch::AddToStack('VENDOR_ITEM_' . $itemId, [           // later, to all watchers
    'module_id' => 'vendor.module',
    'command' => 'itemUpdated',
    'params' => ['id' => $itemId],
]);

• Add() は現在のユーザーに対して OnAfterEpilog で書き込まれます。別のユーザーに対して、または Web リクエストの外で実行する場合は、第 3 引数に true（即時）を渡してください。
• ウォッチの有効期間は約 30 分です。ページでは BX.PULL.extendWatch(tag) を使って有効状態を維持します。
• AddToStack() はタグの配列と skip_users を受け付けます。

JS でサブスクライブする

rel に pull.client を追加します（import { PULL } from 'pull.client'、グローバル変数は BX.PULL）。moduleId は小文字である必要があります。

// With command: (params, extra, command, info)
const off = BX.PULL.subscribe({
    moduleId: 'vendor.module',
    command: 'itemUpdated',
    callback: (params, extra, command) => reload(params.id),
});

// Without command: one object for every module command
BX.PULL.subscribe({
    moduleId: 'vendor.module',
    callback: (data) => { /* data.command, data.params, data.extra */ },
});

BX.PULL.extendWatch('VENDOR_ITEM_' + itemId);
off(); // unsubscribe

• ハンドラーオブジェクト：BX.PULL.attachCommandHandler({ getModuleId: () => 'vendor.module', handleItemUpdated(params, extra) {} }) — メソッド handle と先頭を大文字にしたコマンドを使用するか、getMap() を使用します。
• Vue：mounted で this.$Bitrix.PullClient.get().subscribe(...) を呼び出し、返された関数を unmounted で呼び出します（bitrix-vue）。
• Pull のグローバル protobuf は使わないでください。pull 26.100 以降は最小構成のビルドのため、load、parse、Root、Type は削除されています。独自の protobufjs をバンドルし、globalThis.protobuf に割り当てないでください。Pull は globalThis.protobuf.roots['push-server'] を読み取ります。

モバイルプッシュ

\Bitrix\Pull\Push::add($users, ['module_id' => 'vendor.module', 'push' => ['message' => 'Text', 'params' => [...]]]) は、プッシュ用のカーネルエントリーポイントです（command／params を破棄します）。または、両方を送信するには Event::add() に push／pushParamsCallback を追加します。CPullStack はレガシーです。

バッジの更新：Push::add($userId, ['module_id' => 'pull', 'push' => ['badge' => 'Y']])。CPushManager::sendBadges() は pull 26.0 で削除され（致命的エラー）、MobileCounter::send() は何もしません。Push::add() の呼び出しはすべてのバージョンで動作します。

チェックリスト

• PHP と JS で module_id／command が同一である（モジュール名は小文字）。
• ペイロードを小さくし、UTF-8 を使用する。大きなデータは必要に応じて取得する。
• タグ：レンダリング時に CPullWatch::Add を呼び出し、JS で extendWatch を使用する。
• アンマウント／破棄時にサブスクリプションを解除する。
• Pull をジョブキューとして使わない。