Open the right app screen from a push notification

A notification tap should open the current item named in the message. Build the destination and its authorization checks before sending; a notification is never proof that the person holding the device may access the record.

Choose a stable destination

Use a route such as https://app.example.com/orders/FN-1042, with an opaque application reference and no access credentials or private details. The server checks the signed-in customer's access and loads current order state. Configure Apple universal links or Android app links if the HTTPS destination should open your installed app.

A direct Channels API Push message supports a single link action in body.list.actions:

Code example

{
  "type": "link",
  "link": {
    "text": "View order",
    "url": "https://app.example.com/orders/FN-1042"
  }
}

The complete request shows where that action belongs. For template messages, configure the tap action and any buttons in the Push template. Bird's client interaction model distinguishes OPEN_APP, URL and DEEP_LINK; do not add invented fields for those actions to the basic message body.

Carry the destination through startup

Use one application routing decision for notification taps, ordinary links and restored navigation. Initialize account state first; hold an allowed destination while sign-in completes. Authorize the record after sign-in, then render it. Store only a safe relative destination, and clear it after use or account change.

Code example

Notification received → presentation follows app and OS settings
Customer taps → app starts/resumes → validate destination
                                     ├─ invalid → safe app home
                                     └─ allowed → establish account
                                                   ├─ signed out → sign in → authorize record
                                                   └─ signed in ───────────→ authorize record
                                                                              ├─ allowed → current record
                                                                              └─ denied/missing → useful recovery

For web cold starts, use the HTTPS URL action above and route from the URL when the app opens. With automaticallyOpenDeepLinks disabled, a custom DEEP_LINK does not open a closed browser window. The following custom-scheme listener applies only when an existing page can receive the SDK event.

On that page, Bird emits bird-sdk-push-notification with detail.type equal to Received, Tap or Button. detail.action can include type, identifier and uri. A receipt event must not navigate the page. The following application helper accepts a specific custom deep-link shape, then returns a safe relative destination for your router:

Code example

function destinationFromPush(detail) {
  if (!["Tap", "Button"].includes(detail?.type)) return null;
  if (detail.action?.type !== "DEEP_LINK" || !detail.action.uri) return null;
  try {
    const url = new URL(detail.action.uri);
    if (url.protocol !== "fieldnotes:" || url.hostname !== "orders") return null;
    if (url.username || url.password || url.search || url.hash) return null;
    if (!/^\/[A-Za-z0-9-]+$/.test(url.pathname)) return null;
    return `/orders${url.pathname}`;
  } catch {
    return null;
  }
}

// Existing-page routing only; use the HTTPS URL action for a closed window.
// Configure automaticallyOpenDeepLinks: false to let this page own custom links.
Bird.eventTarget.addEventListener("bird-sdk-push-notification", (event) => {
  const destination = destinationFromPush(event.detail);
  if (destination) {
    sessionStorage.setItem("pendingPushDestination", destination);
    window.dispatchEvent(new Event("app-route-requested"));
  }
});

For example, a template's fieldnotes://orders/FN-1042 action becomes /orders/FN-1042. app-route-requested and pendingPushDestination are application conventions in this example, not Bird SDK events. Your existing page listens for the event and checks the saved destination after sign-in; its backend must authorize the order. Opening a new page uses the HTTPS destination instead of depending on this page's sessionStorage. automaticallyOpenDeepLinks is the Web SDK configuration option when the SDK owns custom-link opening. Use one navigation owner to avoid opening the same destination twice. See Web interaction handling.

For Android, handle the link in both the initial activity intent and onNewIntent; use bird.notifications.getNotificationInteraction(intent) when consuming Bird's notification broadcasts. For iOS, forward the notification response to bird.notifications.handleNotificationResponse and pass the resulting action to your router. The Android interaction guide and Swift interaction guide show the platform callbacks.

Test the message and the app together

Send to one controlled device with the first-notification guide. Test notification presentation and navigation separately:

State	Display check	Tap and destination check
App in foreground	Confirm the intended banner or in-app presentation, with no duplicate display.	Receipt alone does not navigate; a deliberate tap opens current state.
App in background	Check OS settings, notification channels and SDK handling.	Resume, initialize account state, then apply the destination.
Cold start	Verify that the installed app receives the chosen notification format.	Retain the destination until navigation is ready.
Signed out	Avoid private lock-screen detail.	Sign in, authorize, then continue to the allowed record.
Another account signed in	Check device association; pause incorrect private sends.	Deny the other customer's record without exposing details.
Record changed or deleted	Copy remains useful even if the state changes.	Show current state or return to the customer's list.
App absent	Test the configured HTTPS fallback.	Show a useful web page with the same access checks.

An order tap must not mark the order collected. A booking reminder must not confirm attendance. Those actions belong to authenticated application workflows.

Measure the next action

Retain the message/campaign reference separately from the authorized application outcome. Count a notification tap as an interaction and an order view or completed booking as its own event. A receipt, presentation and open are different stages; support and observability differ across platforms.

Follow notification design and measurement, troubleshooting and Push resources.

Related resources

Continue with the documentation, guides and examples for this topic. Resources are in English.

Explore the capabilityPush notifications

Get an implementation brief