Message-push Integration

Whale order, account, and other business messages can reach a Customer in two ways: Whale manages the cloud-push channels and delivers directly to devices, or Whale forwards the message to Broker Server and Broker decides whether and how to distribute it.

This page explains the overall options and responsibility boundaries. The original configuration fields and complete examples are retained in:

• Choose a message-push option
• Push-channel information form
• Broker-owned push channels

flowchart LR
    A[Whale creates business message] --> B[Whale cloud-push service]
    B --> C[Apple APNs]
    B --> D[Android vendor channels]
    C --> E[Broker App]
    D --> E
    E --> F[Pass standard message to WhaleApp SDK]

1. Broker confirms production and UAT iOS Bundle IDs, Android Package Names, and required channels.
2. Broker creates the App and enables push in Apple or Android vendor consoles, then generates credentials.
3. Broker delivers credentials to Whale through the agreed encrypted channel.
4. Whale creates and configures the cloud-push application for each environment.
5. Broker App implements notification permission, device-token registration, and WhaleApp SDK message handling.
6. Both parties test foreground, background, terminated-App, and notification-tap behavior.

Mark unused channels explicitly as unused. If production and UAT share a Package Name, only one set may be submitted, but confirm that the vendor console permits sharing across both environments.

For every environment, also record:

• Environment: UAT or production.
• Android Package Name.
• App name or project ID in the vendor console.
• Credential expiry, rotation contact, and planned rotation time.

Broker can provide either an APNs token-signing key (.p8) or certificate (.p12); normally only one is needed.

If UAT and production share a Bundle ID, state this explicitly in the delivery form rather than assuming whether credentials can be reused.

Whale sends standard business messages to an endpoint provided by Broker. Broker can apply filtering, template rendering, Customer preferences, and multi-channel distribution.

sequenceDiagram
    autonumber
    participant Whale as Whale message service
    participant Endpoint as Broker endpoint
    participant Center as Broker message center
    participant Channel as Broker push channel
    participant App as Broker App / WhaleApp SDK
    Whale->>Endpoint: POST message with X-Api-Key and X-Trace-Id
    Endpoint->>Endpoint: Authenticate and process post_id under project rules
    Endpoint-->>Whale: Return processing result
    Endpoint->>Center: Persist and apply distribution policy
    Center->>Channel: Deliver to Customer device
    Channel-->>App: title, body, user_info
    App->>App: Pass standard message to WhaleApp SDK

• UAT and production HTTPS endpoints.
• Authentication method and secure key-delivery flow.
• Network allowlist, TLS, and optional mTLS requirements.
• Request timeout, maximum body size, and rate limit.
• Technical contact, monitoring method, and production-escalation channel.

The historical design uses POST with these headers:

Example request:

{
  "member_ids": ["<member-id>"],
  "template_key": "order_done_v2_lb",
  "post_id": "<unique-message-id>",
  "channel": "push",
  "language": "en",
  "title": "Buy order fully filled",
  "body": "Security: Example Stock\nQuantity: 500",
  "template_params": {
    "quantity": "500",
    "order_id": "<order-id>"
  },
  "pre_params": {
    "member_real_name": "Example Customer"
  },
  "user_info": {
    "t": "order_done_v2_lb",
    "tn": "<event-trace-id>",
    "id": "<unique-message-id>",
    "lb_push_from": "xx",
    "link": "broker-app://trade/order-detail?id=<order-id>",
    "json": "{\"message_type\":\"order_done_v2_lb\"}"
  }
}

Example response:

{
  "success": true,
  "message": "success",
  "code": 0
}

Under the historical convention, code: 0 means success and a non-zero code means failure. Agree retry policy, attempts, backoff, and retryable codes before go-live. The receiving side must not assume that every failure will be delivered again.

• Accept HTTPS only and validate X-Api-Key if required by the project; production keys should support rotation.
• Use post_id for idempotency and retain deduplication records for the required business period.
• Validate and durably accept quickly, then perform vendor delivery asynchronously to avoid upstream timeout.
• Tolerate unknown additive fields so new template parameters do not reject the message.
• Monitor authentication, validation, duplicates, persistence, and downstream delivery failures.
• Log X-Trace-Id, post_id, and outcome without logging secrets or complete personal data.
• Agree how partial failure across several member_ids is represented and compensated.

Both server paths ultimately deliver the same structure to WhaleApp SDK:

{
  "title": "Message title",
  "body": "Message summary",
  "user_info": {
    "t": "message type",
    "tn": "event trace ID",
    "id": "message ID",
    "lb_push_from": "message source",
    "link": "navigation link",
    "json": "business JSON string"
  }
}

Broker App integrating WhaleApp SDK must:

1. Request OS notification permission and obtain the platform device token.
2. Register the token with the selected push service and update its binding when the token, logged-in Customer, or logout state changes.
3. Parse the same standard structure for foreground receipt, background taps, and cold-start taps.
4. Pass title, body, and complete user_info to the current WhaleApp SDK message handler.
5. Validate the link scheme, destination, and parameters against an allowlist before navigation.
6. Tolerate unknown message types and missing optional fields and record useful redacted diagnostics.

Cover at least:

• No mixing of UAT and production App identifiers, credentials, or messages.
• Correct mapping of one and several member_ids to Customers.
• Repeated delivery of one post_id creates only one visible notification.
• Defined behavior in foreground, background, and terminated states.
• No incorrect delivery after logout, account switch, or disabled permission.
• Simplified Chinese, Traditional Chinese, English, and fallback language meet product expectations.
• Taps reach the correct page and invalid or expired links degrade safely.
• Broker endpoint timeout, failure response, and downstream vendor failure are observable.
• Credential rotation expires the old key as planned without interrupting delivery.

Message push is part of go-live acceptance alongside account, cash, and trading flows. See Broker onboarding overview for the full delivery lifecycle.