Testing your app
Load your dev server inside your own community, then inspect API calls and webhook deliveries.
Localhost URLs in your own workspace
While you build, point the app's Experience URL and Dashboard URL at your dev server, for example http://localhost:3000/experience. Plain http is allowed for localhost, 127.0.0.1 and [::1]; any other host needs https. Use exactly one of those three for a local server: other loopback addresses (127.0.0.2, 0.0.0.0, [::ffff:127.0.0.1]), localhost., *.localhost and private or link-local IP addresses are refused.
A localhost URL loads from the viewer's own machine, so it only works for you. Planeward therefore keeps such an app in your workspace:
- It can only be installed in the workspace that created it. The install link is refused elsewhere with This app is in local development and can only be installed in its own workspace.
- You can't switch to a localhost URL while the app is installed in another workspace. Uninstall it there first.
- Official apps can't use localhost URLs.
- An older install in another workspace, made before these rules, stops working: API calls get
403with This app is in local development and only works in its own workspace., and its webhooks are skipped.
The app shows a Local dev badge in Settings › Apps › Developer, and its channel shows Local dev in the community sidebar.
Install it in your workspace, add it as a channel, start your dev server and open the channel.
Browsers
- Chrome may ask to allow the community site to access devices on your local network. Allow it, or the frame stays blank.
- Safari blocks
http://localhostinside anhttpspage. Serve your dev server over HTTPS (for examplenext dev --experimental-https) and usehttps://localhost:3000/....
Webhooks still need a public URL
Planeward can't reach your machine, so the Webhook URL must be public HTTPS even for a local dev app. Run a tunnel such as cloudflared or ngrok and use the tunnel URL for the webhook only. The frame URLs can stay on localhost.
Switch every URL to your deployed HTTPS app before sharing the install link.
Requests
Open Settings › Apps › Developer, select an app's ⋯ menu and choose Requests. It lists every API call your app's installations made: time, workspace, method, endpoint, status, latency and error. Filter by status (2xx, 4xx, 5xx) or search by endpoint.
Open a row to see the full request and response. Bodies are shown only for installations in your own workspace. Calls from other workspaces show the method, endpoint and status without bodies, since they can hold that workspace's data.
Missing scopes
A call to an endpoint whose scope the installation wasn't granted returns 403:
{
"error": "Insufficient API key permissions",
"missingScope": "EVENTS_READ"
}In Requests the row reads missing EVENTS_READ. The SDK sets error.missingScope on PlanewardApiError.
To fix it, add the scope to the app in Settings › Apps › Developer. A workspace that already installed the app approves the new scope on Community › Apps, where the app shows Permissions to review; no reinstall is needed. See the scope list.
Scope 403s also show in an API key's Usage tab in Developer → API Keys.
Deliveries
Deliveries (in the same ⋯ menu) lists every webhook sent to your app's webhook URL: time, event, workspace, status and response code. Open a row for the payload and your server's response. As with Requests, payloads and responses are shown only for installations in your own workspace.
Send test event
Send test event sends a signed event to your webhook URL through the normal delivery path.
- Pick the Installation. The event is sent for that workspace.
- Pick the Event. The list has
app.installedplus every event your app's requested scopes cover. - Select Send event. The result opens in Deliveries.
app.installed is built from the chosen installation. Every other event carries fixed sample data with placeholder ids, not real records. The envelope has no test flag, so your handler treats it like a live event; don't write sample ids to production data.
The app needs a webhook URL first.
Redeliver
Redeliver on a delivery sends it again with the same X-Planeward-Delivery id. A handler that dedupes on that id skips it, so clear the stored id first when you want it processed again.
Notifications
Notifications need a real member to receive them, so a test needs two things:
- A member account. Use a community member's id (their
memberId). Staff can't be targeted: a staff id comes back asmember_not_found, so sign in to your community with a separate member account, such as a complimentary one. Every member also needs to beACTIVE. - An app channel that
@everyonecan view. Without one every member is skipped aschannel_not_visible. Keep a local-dev app's channel in a staff-only category while you build and add it to a public category for the test.
Then send one and check the result in Requests. In the member's session the notification shows in the bell and, if that member turned push on, as a push notification; clicking it opens your app at the href. The member can switch your app off under Settings › Notifications › Apps, and you won't see a difference in the response, so don't use accepted to confirm delivery.
Remember the limit while testing: 10 notifications per member per app per hour. Test with a key, or with another member, once you hit it.
In the emulator
The planeward dev emulator has an Inbox tab. Notifications your app sends appear there, newest first, filterable by member. Click one to open your app as that member at its path, which is how you check a deep link without a community. The emulator does not send push, show a bell or track read state, and a muted member is not simulated. Its hourly limit is a rolling 60 minutes, slightly stricter than production's fixed hour, and it never returns channel_not_visible.
Planeward Docs