> ## 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.

# Aplicativo de exemplo: deep links e cliques em notificações

> Como o aplicativo de exemplo Clean Beans leva um push tocado para a tela certa, trata botões de ação e adiamento, e abre a partir de Universal Links.

Esta página faz parte de [Aplicativo de exemplo: uma integração completa do OneSignal](https://documentation.onesignal.com/docs/pt-BR/example-full-integration-overview.md), que acompanha um aplicativo real do início ao fim. O aplicativo é o **Clean Beans**, uma escala de limpeza para casas compartilhadas, construído com Expo (React Native) e um backend Supabase.

Uma notificação só é útil se tocar nela levar você ao lugar certo. O Clean Beans trata quatro formas de entrar no aplicativo: um push tocado, um botão tocado em um push, um link com esquema personalizado e um link web comum.

## Rotear um push tocado \\

Todo push carrega um campo `data.type`. O aplicativo escuta os toques, lê o tipo e abre a tela correspondente.

```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` | Abre |
| - | - |
| `daily_digest`, `overdue_reminder`, `upcoming_cleaning` | A aba Clean |
| `session_completed`, `kudos` | O feed de atividades |
| `join_approved`, `member_lapsed` | A tela da casa |
| `reengagement` | A aba Clean |

Dois desses tipos vêm de Journeys, que este guia não aborda. `reengagement` é definido nos pushes de uma Journey de reconquista criada no painel. `member_lapsed` é um push para os donos e administradores de uma casa, enviado pelo backend quando essa Journey informa que um membro parou de limpar. Eles são roteados aqui como qualquer outro push.

> [!TIP]
>
> Rotear por um tipo que você controla é mais robusto do que analisar uma URL. Se uma tela mudar de lugar, você altera uma única instrução `switch`, e todos os pushes enviados antes da mudança continuam abrindo corretamente.

## Botões de ação: mais de uma coisa para tocar \\

Um push pode ter botões. Os pushes de tarefas oferecem **Start cleaning** e **Snooze 1h**, e o push "um colega de casa terminou a limpeza" oferece **Send kudos**. As pessoas revelam os botões expandindo a notificação, o que no iOS é um toque longo.

![Uma notificação push expandida com os botões Start cleaning e Snooze 1h](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-action-buttons.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=0a850d439deea8f483c8dfe532fb8e93)

Um lembrete expandido com seus dois botões de ação.

O backend adiciona os botões à solicitação. Cada um tem um `id` e um rótulo.

```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' },
];
```

Tocar em um botão abre o aplicativo, e o listener de clique mostrado acima recebe o `id` do botão como `event.result.actionId`. Um toque na própria notificação não tem `actionId`. O aplicativo verifica primeiro se há um botão e, se não houver, volta ao roteamento normal.

```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 };
  }
}
```

O **adiamento** precisa do backend, porque o aplicativo não pode enviar push. Ele chama uma função que agenda outro lembrete com `send_after`. O OneSignal guarda a mensagem até lá, então nada precisa ficar rodando por uma hora.

```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]
>
> Todo toque em botão também é registrado como evento personalizado, `push_action_clicked`. Uma Journey não pode ramificar diretamente com base em um botão, mas pode aguardar esse evento e ramificar pela propriedade `action_id`.

> [!NOTE]
>
> Tocar em um botão abre o aplicativo por padrão. Tratar um toque sem abrir o aplicativo exige código nativo: uma categoria de notificação no iOS e uma notification service extension no Android.

## Reescrever links recebidos \\

Links de fora do aplicativo usam caminhos curtos como `/clean`. O hook de native intent do Expo Router os reescreve para as rotas reais do aplicativo antes da navegação, então nada fora do aplicativo precisa saber como as telas estão organizadas.

```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)';
  }
}
```

## Abrir o aplicativo a partir de links web comuns \\

Um esquema personalizado como `cleaning-rota://` só funciona se o aplicativo estiver instalado, e muitos aplicativos se recusam a torná-lo clicável. Os Universal Links no iOS e os App Links no Android resolvem isso. São links `https://` comuns que abrem o aplicativo quando ele está instalado e o site quando não está. Isso os torna a escolha certa para links em emails, SMS e mensagens compartilhadas.

Configurá-los exige uma declaração de cada lado: o aplicativo diz a qual domínio pertence, e o site diz qual aplicativo pode abrir seus links.

**1. Declarar o domínio no aplicativo**

```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. Publicar o arquivo de associação da Apple**

Hospede-o em `/.well-known/apple-app-site-association`, via HTTPS, servido como JSON. O ID do aplicativo é seu Apple Team ID seguido do 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. Publicar o arquivo de associação do Android**

Hospede-o em `/.well-known/assetlinks.json`. A impressão digital vem do certificado de assinatura do seu aplicativo. Com o EAS, execute `eas credentials -p android` para encontrá-la.

```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. Usar o link**

A tela da casa compartilha um link de convite. Tocar nele abre a tela de entrada com o código já preenchido.

```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]
>
> O Clean Beans reivindica apenas os caminhos que o aplicativo consegue mostrar. A página inicial fica de fora, então o site de marketing continua abrindo no navegador. O iOS lê o arquivo de associação quando o aplicativo é instalado ou atualizado, então publique o arquivo antes de lançar a compilação.

> [card] [Deep linking](https://documentation.onesignal.com/docs/pt-BR/deep-linking.md)
>
> Como o OneSignal trata URLs em cada plataforma.

> [card] [Payload da notificação](https://documentation.onesignal.com/docs/pt-BR/osnotification-payload.md)
>
> Todos os campos disponíveis no listener de clique.

> [card] [Botões de ação](https://documentation.onesignal.com/docs/pt-BR/action-buttons.md)
>
> Limites de cada plataforma, ícones e tratamento de toques.


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