In-App Notifications (Wallet-Based)

​

Overview

• A dashboard configuration surface to manage allowed browser origins and publishable keys.
• A public two-step wallet authentication flow (challenge → verify) using a publishable key (pk_*).
• A Socket.IO gateway that streams pushes to connected clients and replays pending pushes on reconnect.
• A server-to-server API to send pushes using a secret key (sk_*).

​

Concepts

​

Keys

• Publishable key (pk_*): safe to use in the browser. Used only for the challenge/verify flow.
• Secret key (sk_*): server-to-server only. Used to send pushes programmatically.

​

Allowed origins

• pk_live_* keys map to production origin entries.
• pk_test_* keys map to development origin entries.

​

Dashboard setup (Integrations)

​

1) Check in-app integration status

• publishable keys
• available secret keys
• currently connected SDK sessions
• daily usage limit and usage
• allowed origin count

​

2) Allow your frontend origin

{
  "origin": "https://app.example.com",
  "environment": "production"
}

​

3) Send a test push (optional)

{
  "walletAddress": "0xabc...",
  "title": "Test notification",
  "body": "Your in-app integration is working.",
  "ctaLabel": "Open",
  "ctaUrl": "https://app.example.com"
}

​

Browser SDK auth flow (challenge → verify)

​

Step 1 — Request a challenge message

• x-publishable-key: pk_live_... (or Authorization: Bearer pk_live_...)
• Origin: https://app.example.com

{
  "walletAddress": "0xabc..."
}

{
  "nonceId": "f3c1...",
  "message": "OnchainSuite In-App Push\n\nWallet: 0xabc...\nNonce: ...\nIssued At: ...\nExpires At: ...",
  "expiresAt": "2026-06-22T00:00:00.000Z"
}

​

Step 2 — Sign and verify

• x-publishable-key: pk_live_... (or Authorization: Bearer pk_live_...)
• Origin: https://app.example.com

{
  "walletAddress": "0xabc...",
  "signature": "0x..."
}

{
  "token": "<inapp-session-jwt>",
  "wsUrl": "https://api.onchainsuite.com/api/v1/inapp/register",
  "expiresAt": "2026-06-29T00:00:00.000Z"
}

​

Example: signing with ethers

import { BrowserProvider } from "ethers";

const provider = new BrowserProvider(window.ethereum);
const signer = await provider.getSigner();
const signature = await signer.signMessage(message);

​

Real-time delivery via Socket.IO

• /api/v1/inapp/register

• handshake.auth.token = <session jwt>
• or Authorization: Bearer <session jwt>
• or query param ?t=<session jwt>

​

Example: connect and listen for pushes

import { io } from "socket.io-client";

const socket = io("https://api.onchainsuite.com", {
  path: "/api/v1/inapp/register",
  transports: ["websocket"],
  auth: { token },
});

socket.on("connect", () => {
  socket.emit("REGISTER", { walletAddress });
});

socket.on("PUSH", (push) => {
  // push shape includes: deliveryId, campaignRunId, title, body, cta?, createdAt, expiresAt
  console.log("Push received", push);
  socket.emit("EVENT", {
    campaignRunId: push.campaignRunId,
    deliveryId: push.deliveryId,
    type: "delivered",
  });
});

​

Client events

• REGISTER (optional but recommended): confirms the wallet for the connection
• EVENT: records interaction events (delivered, viewed, dismissed, clicked)

​

Sending pushes (server-to-server)

• Authorization: Bearer sk_... (or x-secret-key: sk_...)

{
  "walletAddress": "0xabc...",
  "title": "You received tokens",
  "body": "A transfer just hit your wallet.",
  "ctaLabel": "View transaction",
  "ctaUrl": "https://app.example.com/tx/0x...",
  "automationId": "goldrush_transfer_alert"
}

{
  "ok": true,
  "campaignRunId": "cr_...",
  "deliveryId": "d_...",
  "deliveredNow": true,
  "expiresAt": "2026-06-25T00:00:00.000Z"
}

​

Automations integration (sending in-app from workflows)

• creates a CampaignRun for tracking
• writes a DeliveryEvent row for analytics (sent, plus interaction events)
• stores a short-lived pending list per wallet in cache (replayed on reconnect)

​

Limits, TTLs, and environment variables

​

Push TTL

• Pushes expire after ttlHours (clamped to 1..72 hours, default 72).
• Expired/dismissed/clicked pushes are pruned and won’t be replayed.
• Per-wallet pending list is capped to the 10 most recent pushes.

​

Daily quota

• INAPP_DAILY_LIMIT (default 50000) limits pushes per org per UTC day (429 if exceeded).

​

Session token TTL and secrets

• INAPP_SESSION_SECRET must be set (fallbacks: JWT_ACCESS_SECRET, BETTER_AUTH_SECRET)
• INAPP_SESSION_TTL_SECONDS controls session expiry (clamped to 10 minutes..30 days; default 7 days)

​

Troubleshooting

• If /inapp/challenge or /inapp/verify returns Origin not allowed:
  • confirm the browser’s Origin matches the configured allowed origin exactly (scheme + host + port)
  • confirm you used the correct publishable key (pk_live_* vs pk_test_*)
• If pushes are not delivered live:
  • confirm the client is connected to Socket.IO and listening for PUSH
  • deliveredNow: false means the wallet was offline; the push will be replayed on reconnect until it expires