Push Compliance Guide

Background: Xiaomi Push changed its message template requirements and push limits as of 2026-07-01 (source: Tencent Cloud IM push service announcements); every vendor integrating the Xiaomi channel must finish adapting by 2026-12-31. This document is the imcore-side checklist, the code guardrails already shipped, and the monitoring responsibility table. Related backlog: tech-scan TODO P0-2 / product candidate 3 “offline push vendor compliance adaptation and token validation” (2026-09-22 cycle).

1. Already Shipped on the Code Side (2026-09-22)

Guardrail Location Notes
Pre-registration token format validation servers/websocket/push_token_format.go + push_controller.go Rejects tokens that are certainly invalid per vendor (out-of-range length/whitespace/control characters/APNs not 64-char hex), returning 1001 with an error message naming the vendor; unknown vendors are not validated (forward compatibility)
Xiaomi title/description truncation servers/task/push_provider_oem.go sendXiaomiPush Truncates by rune in alert mode (title defaults to 50, description to 128; tunable via push.xiaomi.max_title_chars / max_body_chars), so over-limit payloads are no longer rejected wholesale by the vendor; an empty description falls back to the title, and if both are empty the send is blocked
VoIP tokens under the same rule Same registration controller PushKit tokens go through the same 64-hex validation as the main APNs token

2. Deployment-Side Checklist (To Complete in the Vendor Console, Due 12-31)

Work through the Xiaomi developer console (Push → App Configuration) item by item, checking off each one as you complete it:

  • Message template review: the self-classified message templates required by the 2026-07-01 rules have been submitted and approved in the console; the title/description imcore sends matches the approved templates (passthrough messages are not bound by templates, but alert pushes must match).
  • Notification channel: the app has created a notification channel in the Xiaomi console; if templates require binding a channel, add the channel parameter to the push.xiaomi configuration (imcore currently sends no channel field — a known gap, see §4).
  • Rate limits / daily quota: confirm the daily push quota of the app’s current plan; if you are close to the cap, set an alert in monitoring (§3) for push_xiaomi_rate_limited-class error codes (Xiaomi returns the 22103x family of throttling codes).
  • Credential validity: push.xiaomi.app_secret matches the console AppSecret and has not been rotated; after rotation, hot-reload via admin runtime configuration.
  • Live test: send one alert push built from the new template to a real device and confirm that it appears in the notification shade and shows as delivered in the vendor console’s push records.

3. Announcement Monitoring (Owners To Be Assigned)

Source Frequency Owner
Xiaomi Push developer announcements Weekly To be assigned
Tencent Cloud IM service announcements (cross-vendor policy signals) Weekly (folded into the Friday IM scan) Folded into the scan_im_updates.py weekly report process
Huawei/Honor/OPPO/vivo developer console in-site messages Monthly To be assigned

Alert signals: vendor error-code classification in the servers/task push failure logs (classifyXiaomiResponse etc.) and the push_provider retry-rate metric; 30 days before a new policy takes effect, re-check the quota and template status once in the weekly meeting.

4. Known Gaps (Follow-ups)

  1. channel field: imcore’s Xiaomi alert pushes currently carry no notification channel ID. If console template review requires binding a channel, channel_id must be added to sendXiaomiPush (provided via configuration or per-app package) — to be implemented once the console check results are confirmed.
  2. Delivery-rate dashboard: push results are currently recorded in the task table and logs; an aggregated per-vendor/per-app delivery dashboard is an observability enhancement to be planned together with the ops metrics dashboards (imctl) — deferred for now.
  3. Token lifecycle: automatic deregistration after a vendor-side token becomes invalid (uninstall/reinstall) depends on vendor error-code receipts (e.g. Xiaomi ErrBadRegID); failures are only logged today, and the deregistration policy is TBD.