> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Example app: deep links and notification clicks

> How the Clean Beans example app routes a tapped push to the right screen, handles action buttons and snooze, and opens from Universal Links.

This page is part of [Example app: a full OneSignal integration](https://documentation.onesignal.com/docs/en/example-full-integration-overview.md), which follows one real app from end to end. The app is **Clean Beans**, a cleaning rota for shared homes, built with Expo (React Native) and a Supabase backend.

A notification is only useful if tapping it takes you to the right place. Clean Beans handles four ways into the app: a tapped push, a tapped button on a push, a custom-scheme link, and an ordinary web link.

## Route a tapped push

Every push carries a `data.type` field. The app listens for taps, reads the type, and opens the matching screen.

```typescript app/_layout.tsx theme={null}
OneSignal.Notifications.addEventListener('click', (event: NotificationClickEvent) => {
  const data = event.notification.additionalData as Record<string, string> | undefined;
  if (!data?.type) return;

  // Mark inbox message as read (best-effort, fire-and-forget)
  const notificationId = event.notification.notificationId;
  if (notificationId) {
    supabase
      .from('inbox_messages')
      .update({ read: true })
      .eq('onesignal_message_id', notificationId)
      .then();
  }

  // Small delay to let the app finish initialising if cold-launched
  setTimeout(() => {
    // A tap on an action button ("Snooze 1h", "Send kudos", ...) carries an
    // actionId. A tap on the notification itself does not.
    const action = handlePushAction(event.result.actionId, data);
    if (action.handled) {
      if (action.route) router.push(action.route as any);
      return;
    }

    switch (data.type) {
      case 'daily_digest':
      case 'upcoming_cleaning':
      case 'overdue_reminder':
      case 'reengagement':
        router.push('/(tabs)/clean');
        break;
      case 'session_completed':
      case 'kudos':
        router.push('/activity');
        break;
      case 'join_approved':
      case 'member_lapsed':
        router.push('/household');
        break;
      default:
        break;
    }
  }, 500);
});
```

| `data.type` | Opens |
| - | - |
| `daily_digest`, `overdue_reminder`, `upcoming_cleaning` | The Clean tab |
| `session_completed`, `kudos` | The activity feed |
| `join_approved`, `member_lapsed` | The household screen |
| `reengagement` | The Clean tab |

Two of those types come from Journeys, which this guide does not cover. `reengagement` is set on the pushes in a win-back Journey built in the dashboard. `member_lapsed` is a push to a household's owners and admins, sent by the backend when that Journey reports that a member has stopped cleaning. They are routed here like any other push.

> [!TIP]
>
> Routing on a type you control is more robust than parsing a URL. If a screen moves, you change one `switch` statement and every push sent before the change still opens correctly.

## Action buttons: more than one thing to tap

A push can carry buttons. The task pushes offer **Start cleaning** and **Snooze 1h**, and the "housemate finished cleaning" push offers **Send kudos**. People reveal the buttons by expanding the notification, which is a long press on iOS.

![An expanded push notification with Start cleaning and Snooze 1h buttons](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-action-buttons.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=0a850d439deea8f483c8dfe532fb8e93)

An expanded reminder with its two action buttons.

The backend adds the buttons to the request. Each has an `id` and a label.

```typescript supabase/functions/_shared/buttons.ts theme={null}
export const TASK_BUTTONS = [
  { id: ACTION_START_CLEANING, text: 'Start cleaning' },
  { id: ACTION_SNOOZE, text: 'Snooze 1h' },
];
```

Tapping a button opens the app, and the click listener shown above receives the button's `id` as `event.result.actionId`. A tap on the notification itself has no `actionId`. The app checks for a button first and falls back to normal routing.

```typescript src/lib/pushActions.ts theme={null}
export function handlePushAction(actionId: string | undefined, data: PushData): ActionOutcome {
  if (!actionId) return { handled: false };

  // Record which button was tapped. As a custom event it can branch a
  // Journey (Wait Until this event) or feed a Conversion Metric.
  OneSignal.User.trackEvent('push_action_clicked', {
    action_id: actionId,
    notification_type: data?.type ?? 'unknown',
  });

  switch (actionId) {
    case ACTION_START_CLEANING:
      return { handled: true, route: '/(tabs)/clean' };

    case ACTION_SNOOZE:
      snoozeReminder();
      return { handled: true, route: null };

    case ACTION_SEND_KUDOS:
      sendKudosFromPush(data);
      return { handled: true, route: '/activity' };

    default:
      return { handled: false };
  }
}
```

**Snooze** needs the backend, because the app cannot send a push. It calls a function that schedules another reminder with `send_after`. OneSignal holds the message until then, so nothing has to keep running for an hour.

```typescript supabase/functions/snooze-reminder/index.ts theme={null}
const sendAt = new Date(Date.now() + SNOOZE_MINUTES * 60_000);

const onesignalPayload = {
  app_id: ONESIGNAL_APP_ID,
  include_aliases: { external_id: [user.id] },
  target_channel: 'push',
  // OneSignal holds the message and delivers it at this time
  send_after: sendAt.toISOString(),
  // ...
};
```

> [!NOTE]
>
> Every button tap is also recorded as a custom event, `push_action_clicked`. A Journey cannot branch on a button directly, but it can wait for this event and branch on its `action_id` property.

> [!NOTE]
>
> Tapping a button opens the app by default. Handling a tap without opening the app takes native code: a notification category on iOS and a notification service extension on Android.

## Rewrite incoming links

Links from outside the app use short paths such as `/clean`. Expo Router's native intent hook rewrites them to the app's real routes before navigation happens, so nothing outside the app needs to know how the screens are organized.

```typescript app/+native-intent.tsx theme={null}
const PATH_REWRITES: Record<string, string> = {
  // Tab screens — simplified path → grouped route
  '/clean': '/(tabs)/clean',
  '/tasks': '/(tabs)/tasks',
  '/rota': '/(tabs)/rota',
  '/settings': '/(tabs)/settings',
  '/dashboard': '/(tabs)',

  // Standalone screens
  '/streaks': '/streaks',
  '/activity': '/activity',

  // Convenience aliases
  '/join': '/join-household',
  '/notifications': '/notification-settings',
};

export function redirectSystemPath({
  path,
  initial,
}: {
  path: string;
  initial: boolean;
}): string {
  try {
    // Parse the incoming URL to extract path and query string
    const url = new URL(path, 'cleaning-rota://app');
    const pathname = url.pathname || '/';
    const search = url.search || '';

    // Check for a rewrite match (exact path without query string)
    const rewritten = PATH_REWRITES[pathname];
    if (rewritten) {
      return rewritten + search;
    }

    // Universal Link / App Link with no rewrite: hand the router just the
    // path, not the full https URL
    if (url.protocol === 'https:' || url.protocol === 'http:') {
      return pathname + search;
    }

    // No rewrite needed — pass through as-is
    return path;
  } catch {
    // Never crash in this function — fall back to home screen
    return '/(tabs)';
  }
}
```

## Open the app from ordinary web links

A custom scheme such as `cleaning-rota://` only works if the app is installed, and many apps refuse to make it tappable. Universal Links on iOS and App Links on Android solve this. They are normal `https://` links that open the app when it is installed and the website when it is not. That makes them the right choice for links in emails, SMS, and shared messages.

Setting them up takes a declaration on each side: the app says which domain it belongs to, and the website says which app may open its links.

**1. Declare the domain in the app**

```json app.json theme={null}
{
  "expo": {
    "ios": {
      "associatedDomains": ["applinks:cleanbeansapp.com"]
    },
    "android": {
      "intentFilters": [
        {
          "action": "VIEW",
          "autoVerify": true,
          "data": [
            { "scheme": "https", "host": "cleanbeansapp.com", "pathPrefix": "/join" },
            { "scheme": "https", "host": "cleanbeansapp.com", "pathPrefix": "/clean" }
          ],
          "category": ["BROWSABLE", "DEFAULT"]
        }
      ]
    }
  }
}
```

**2. Publish the Apple association file**

Host it at `/.well-known/apple-app-site-association`, over HTTPS, served as JSON. The app ID is your Apple Team ID followed by the bundle identifier.

```json website/.well-known/apple-app-site-association theme={null}
{
  "applinks": {
    "details": [
      {
        "appIDs": ["YOUR_TEAM_ID.com.onesignal.cleaningapp"],
        "components": [
          { "/": "/join", "comment": "Opens /join in the Clean Beans app" },
          { "/": "/clean", "comment": "Opens /clean in the Clean Beans app" }
        ]
      }
    ]
  }
}
```

**3. Publish the Android association file**

Host it at `/.well-known/assetlinks.json`. The fingerprint comes from your app's signing certificate. With EAS, run `eas credentials -p android` to find it.

```json website/.well-known/assetlinks.json theme={null}
[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.onesignal.cleaningapp",
      "sha256_cert_fingerprints": ["YOUR_SHA256_FINGERPRINT"]
    }
  }
]
```

**4. Use the link**

The household screen shares an invite link. Tapping it opens the join screen with the code already filled in.

```typescript app/household.tsx theme={null}
message: `Join my household "${activeHousehold.name}" on Clean Beans! Tap https://cleanbeansapp.com/join?code=${encodeURIComponent(activeHousehold.inviteCode)} or use invite code: ${activeHousehold.inviteCode}`,
```

```typescript app/join-household.tsx theme={null}
const params = useLocalSearchParams<{ code?: string }>();
const [code, setCode] = useState(typeof params.code === 'string' ? params.code : '');
```

> [!NOTE]
>
> Clean Beans only claims the paths the app can show. The home page is left alone, so the marketing site still opens in the browser. iOS reads the association file when the app is installed or updated, so publish the file before you release the build.

> [card] [Deep linking](https://documentation.onesignal.com/docs/en/deep-linking.md)
>
> How OneSignal handles URLs on each platform.

> [card] [Notification payload](https://documentation.onesignal.com/docs/en/osnotification-payload.md)
>
> Every field available in the click listener.

> [card] [Action buttons](https://documentation.onesignal.com/docs/en/action-buttons.md)
>
> Platform limits, icons, and handling taps.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.