postMessage protocol
The iframe handshake, for apps that don't use the SDK.
@planeward/sdk implements this for you. Use it directly only if you can't use the SDK. Protocol version: 1.
Every message is a plain object with a type.
Messages
| Type | Direction | Payload |
|---|---|---|
planeward:app:ready | app → host | { type, version: 1 } |
planeward:app:token-request | app → host | { type, requestId: string } |
planeward:app:token | host → app | { type, requestId: string | null, token: string, expiresAt: number, context: { view, channelId, theme } } |
planeward:app:theme | host → app | { type, theme: "light" | "dark" } |
planeward:app:error | host → app | { type, requestId: string | null, message: string } |
expiresAtis milliseconds since epoch.context.viewisexperienceordashboard;context.channelIdisstring | null;context.themeislightordark.- The host answers
readywith an unsolicitedtoken(requestId: null). - Send
token-requestwith a freshrequestIdto get a new token beforeexpiresAt. The reply carries the samerequestId, as does anyerror.
Origin rules
- The host only accepts messages from your iframe's window whose origin matches the origin of the app's configured URL, and posts only to that origin.
- In your app, only accept messages from
window.parent. Lock to the origin of the first validtokenmessage, and ignore other origins after that. - After the handshake, post to the locked host origin, never
"*".
let hostOrigin: string | null = null;
window.addEventListener("message", (event) => {
if (event.source !== window.parent) return;
if (hostOrigin && event.origin !== hostOrigin) return;
if (event.data?.type === "planeward:app:token") {
hostOrigin ??= event.origin;
// event.data.token, event.data.context
}
});
window.parent.postMessage({ type: "planeward:app:ready", version: 1 }, "*");The first ready has to go out before you know the host origin. Send nothing else until you have locked it.
The SDK follows the same rules. To accept only known hosts instead of locking to the first one, pass allowedHostOrigins to createPlanewardApp. Communities can run on custom domains, so only do this when you know every host your app is installed on.
Deep links
A notification your app sends carries a path, href. When a member clicks it, the community opens your app's channel and loads your iframe at that path instead of at your Experience URL. The same link works for anyone you give it to: /channels/{channelId}?appPath=<encoded path>.
- How the path resolves. The path is resolved against the origin of your Experience URL, so
/orders/123?tab=itemsonhttps://app.example.com/experienceloadshttps://app.example.com/orders/123?tab=items. The path replaces your Experience URL's own path and query. The origin never changes: the community checks it and falls back to the Experience URL otherwise. - The handshake is the same. The page loads in the usual iframe and goes through the normal
readyandtokenexchange, so you identify the viewer the same way as on any other load. A deep link carries no identity of its own and no new message. Read the path from your own URL; the SDK needs no change. - Treat the path as untrusted. Anyone can craft a link to your channel with any path that passes the rules below. Validate it like any user input, and check that the viewer from the token may see the record it points to. A path doesn't prove the notification was sent to this viewer.
- Don't change data on load. A deep-linked page can open from a crafted link, a reload or a link preview. Show the record and let the viewer act on it; don't mark anything complete, buy or delete just because the page loaded.
- Percent escapes arrive as written.
%2Fand similar reach your app undecoded. Don't decode a path and redirect to it.
Paths that are allowed start with a single /, are at most 512 characters, have no . or .. segments (written plainly or as %2e) and no #. A path that breaks these rules is refused when the app calls the API, so it never reaches a member.
If a link's path is missing, repeated, not a single value or invalid, the community ignores it and opens your app at its Experience URL. Clicking the same link twice doesn't reload the frame. A signed-out visitor is sent to sign in first and returns to the same link; a very long link (more than about 150 characters of path once encoded) can lose the path and open the community home instead, so keep paths short.
Planeward Docs