Push notifications: how they work and how to connect them

npx expo install expo-notifications expo-constants
npm install --global eas-cli
eas init    # создать или привязать проект EAS
eas build   # development build с учётными данными push; профили — в eas.json

{
  "expo": {
    "name": "Orders",
    "scheme": "orders",
    "plugins": [
      [
        "expo-notifications",
        {
          "color": "#1F6FEB",
          "defaultChannel": "orders"
        }
      ]
    ]
  }
}

import { Platform } from 'react-native';
import * as Notifications from 'expo-notifications';
import Constants from 'expo-constants';

export type PushRegistration =
  | { status: 'granted'; token: string }
  | { status: 'denied' } // пользователь отказал — работаем без push
  | { status: 'error'; reason: string }; // нет сети, нет projectId — повторим позже

export async function registerForPush(): Promise<PushRegistration> {
  // Android 13+: системный запрос не появится, пока в приложении нет ни одного канала
  if (Platform.OS === 'android') {
    await Notifications.setNotificationChannelAsync('orders', {
      name: 'Статус заказов',
      importance: Notifications.AndroidImportance.HIGH,
    });
  }

  const current = await Notifications.getPermissionsAsync();
  const permission = current.granted ? current : await Notifications.requestPermissionsAsync();
  if (!permission.granted) return { status: 'denied' };

  const projectId = Constants.expoConfig?.extra?.eas?.projectId ?? Constants.easConfig?.projectId;
  if (!projectId) return { status: 'error', reason: 'no-project-id' };

  try {
    // запрос идёт на серверы Expo — без сети он отклоняется
    const { data } = await Notifications.getExpoPushTokenAsync({ projectId });
    return { status: 'granted', token: data };
  } catch (e) {
    return { status: 'error', reason: String(e) };
  }
}

export async function sendTokenToServer(apiUrl: string, authToken: string, pushToken: string) {
  const response = await fetch(`${apiUrl}/v1/push-tokens`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${authToken}` },
    body: JSON.stringify({ token: pushToken, platform: Platform.OS }),
  });
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
}

import './src/push/handler';
import { useCallback, useState } from 'react';
import { StatusBar } from 'expo-status-bar';
import { Button, StyleSheet, Text, View } from 'react-native';
import { registerForPush, sendTokenToServer, type PushRegistration } from './src/push/registerForPush';
import { useNotificationNavigation } from './src/push/useNotificationNavigation';

const API_URL = process.env.EXPO_PUBLIC_API_URL ?? 'https://api.example.com';

export default function App() {
  const [screen, setScreen] = useState('/orders');
  const [push, setPush] = useState<PushRegistration | null>(null);

  // в проекте с Expo Router здесь будет router.push(url)
  const open = useCallback((url: string) => setScreen(url), []);
  useNotificationNavigation(open);

  async function enablePush() {
    const result = await registerForPush();
    setPush(result);
    if (result.status === 'granted') {
      // токен авторизации берётся из SecureStore после входа; здесь — заглушка
      await sendTokenToServer(API_URL, 'YOUR_AUTH_TOKEN', result.token).catch(() => undefined);
    }
  }

  return (
    <View style={styles.container}>
      <Text>Экран: {screen}</Text>
      {push?.status !== 'granted' && (
        <Button title="Сообщать о статусе заказа" onPress={enablePush} />
      )}
      {push?.status === 'denied' && (
        <Text>Уведомления выключены. Статус заказа всегда виден в разделе «Мои заказы».</Text>
      )}
      <StatusBar style="auto" />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1, padding: 24, paddingTop: 64, gap: 12, backgroundColor: '#fff' },
});

// Хранилище push-токенов. В учебном примере — в памяти; в проекте — таблица
// push_tokens (user_id, token, platform, updated_at) в вашей базе.
export interface TokenStore {
  save(userId: string, token: string): Promise<void>;
  listForUser(userId: string): Promise<string[]>;
  remove(token: string): Promise<void>;
}

export class MemoryTokenStore implements TokenStore {
  private byUser = new Map<string, Set<string>>();

  async save(userId: string, token: string) {
    for (const tokens of this.byUser.values()) tokens.delete(token); // токен принадлежит одному пользователю
    const tokens = this.byUser.get(userId) ?? new Set<string>();
    tokens.add(token);
    this.byUser.set(userId, tokens);
  }

  async listForUser(userId: string) {
    return [...(this.byUser.get(userId) ?? [])];
  }

  async remove(token: string) {
    for (const tokens of this.byUser.values()) tokens.delete(token);
  }
}

curl -H "Content-Type: application/json" -X POST "https://exp.host/--/api/v2/push/send" -d '{
  "to": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]",
  "title": "Заказ готов",
  "body": "Заказ №1042 можно забрать",
  "data": { "url": "/orders/1042" },
  "channelId": "orders"
}'

import { Expo, type ExpoPushMessage } from 'expo-server-sdk';
import type { TokenStore } from './store.ts';

export type PushContent = { title: string; body: string; url: string };
export type PendingReceipt = { receiptId: string; token: string };

export async function notifyUser(
  expo: Expo,
  store: TokenStore,
  userId: string,
  content: PushContent,
): Promise<PendingReceipt[]> {
  const tokens = (await store.listForUser(userId)).filter((t) => Expo.isExpoPushToken(t));
  const messages: ExpoPushMessage[] = tokens.map((to) => ({
    to,
    title: content.title,
    body: content.body,
    data: { url: content.url }, // куда открыть приложение по нажатию
    sound: 'default',
    channelId: 'orders', // канал должен быть создан в приложении
  }));

  const pending: PendingReceipt[] = [];
  // не больше 100 сообщений в запросе — SDK режет на части сам
  for (const chunk of expo.chunkPushNotifications(messages)) {
    const tickets = await expo.sendPushNotificationsAsync(chunk);
    for (const [i, ticket] of tickets.entries()) {
      const token = chunk[i].to as string;
      if (ticket.status === 'ok') pending.push({ receiptId: ticket.id, token });
      else if (ticket.details?.error === 'DeviceNotRegistered') await store.remove(token);
      else console.error('push ticket error', ticket.message);
    }
  }
  return pending; // квитанции проверяем позже — Expo советует через 15 минут
}

export async function checkReceipts(expo: Expo, store: TokenStore, pending: PendingReceipt[]) {
  const tokenById = new Map(pending.map((p) => [p.receiptId, p.token]));
  let failed = 0;
  for (const ids of expo.chunkPushNotificationReceiptIds([...tokenById.keys()])) {
    const receipts = await expo.getPushNotificationReceiptsAsync(ids);
    for (const [id, receipt] of Object.entries(receipts)) {
      if (receipt.status === 'ok') continue;
      failed++;
      // устройство больше не принимает push: перестаём слать на этот токен
      if (receipt.details?.error === 'DeviceNotRegistered') await store.remove(tokenById.get(id)!);
    }
  }
  return { checked: tokenById.size, failed };
}

import { createServer, type IncomingMessage } from 'node:http';
import { Expo } from 'expo-server-sdk';
import { notifyUser } from './push.ts';
import type { TokenStore } from './store.ts';

async function readJson(req: IncomingMessage): Promise<Record<string, unknown>> {
  let raw = '';
  for await (const chunk of req) raw += chunk;
  return raw ? JSON.parse(raw) : {};
}

// Учебная авторизация: в проекте userId берут из проверенной сессии или JWT, а не из заголовка
function userIdOf(req: IncomingMessage): string | null {
  const id = req.headers['x-demo-user'];
  return typeof id === 'string' && id ? id : null;
}

export function createPushServer(expo: Expo, store: TokenStore) {
  return createServer(async (req, res) => {
    const send = (status: number, body?: unknown) => {
      if (body === undefined) return void res.writeHead(status).end();
      res.writeHead(status, { 'content-type': 'application/json' });
      res.end(JSON.stringify(body));
    };
    const userId = userIdOf(req);
    if (!userId) return send(401, { error: 'unauthorized' });

    try {
      if (req.method === 'POST' && req.url === '/v1/push-tokens') {
        const { token } = await readJson(req);
        if (!Expo.isExpoPushToken(token)) return send(400, { error: 'invalid_token' });
        await store.save(userId, token);
        return send(204);
      }
      if (req.method === 'POST' && req.url === '/v1/test-push') {
        const pending = await notifyUser(expo, store, userId, {
          title: 'Заказ готов',
          body: 'Заказ №1042 можно забрать',
          url: '/orders/1042',
        });
        return send(202, { queued: pending.length });
      }
      send(404, { error: 'not_found' });
    } catch (error) {
      console.error(error);
      send(500, { error: 'internal' });
    }
  });
}

import { Expo } from 'expo-server-sdk';
import { createPushServer } from './server.ts';
import { MemoryTokenStore } from './store.ts';

// EXPO_ACCESS_TOKEN нужен, если в настройках проекта включена защита push (Enhanced Security)
const expo = new Expo({ accessToken: process.env.EXPO_ACCESS_TOKEN });
const port = Number(process.env.PORT ?? 3000);

createPushServer(expo, new MemoryTokenStore()).listen(port, () => {
  console.log(`push server on http://localhost:${port}`);
});

import * as Notifications from 'expo-notifications';

// В SDK 57 уведомление при открытом приложении по умолчанию не показывается —
// решаем явно. Вызывается один раз, на верхнем уровне модуля.
Notifications.setNotificationHandler({
  handleNotification: async () => ({
    shouldShowBanner: true,
    shouldShowList: true,
    shouldPlaySound: false,
    shouldSetBadge: false,
  }),
});

// Путь из data.url уведомления — только внутренние экраны из белого списка.
// Push может прийти с устаревшими или подменёнными данными: не открываем что попало.
const ALLOWED = [/^\/orders\/[\w-]+$/, /^\/orders$/, /^\/profile$/];

export function notificationUrl(data: unknown): string | null {
  if (typeof data !== 'object' || data === null) return null;
  const url = (data as { url?: unknown }).url;
  if (typeof url !== 'string') return null;
  return ALLOWED.some((re) => re.test(url)) ? url : null;
}

import { useEffect } from 'react';
import * as Notifications from 'expo-notifications';
import { notificationUrl } from './notificationUrl';

export function useNotificationNavigation(open: (url: string) => void) {
  useEffect(() => {
    function handle(response: Notifications.NotificationResponse) {
      const url = notificationUrl(response.notification.request.content.data);
      if (url) open(url);
    }

    // приложение было закрыто и запущено нажатием на уведомление
    const last = Notifications.getLastNotificationResponse();
    if (last) handle(last);

    // приложение уже работало (на экране или в фоне)
    const subscription = Notifications.addNotificationResponseReceivedListener(handle);
    return () => subscription.remove();
  }, [open]);
}

import { test, beforeEach } from 'node:test';
import assert from 'node:assert/strict';
import type { AddressInfo } from 'node:net';
import { MockAgent } from 'undici';
import { Expo } from 'expo-server-sdk';
import { checkReceipts } from '../src/push.ts';
import { createPushServer } from '../src/server.ts';
import { MemoryTokenStore } from '../src/store.ts';

// плейсхолдеры в формате Expo — настоящих токенов и устройств нет
const TOKEN_A = 'ExponentPushToken[aaaaaaaaaaaaaaaaaaaaaa]';
const TOKEN_B = 'ExponentPushToken[bbbbbbbbbbbbbbbbbbbbbb]';

let agent: MockAgent;
let store: MemoryTokenStore;
let expo: Expo;

beforeEach(() => {
  agent = new MockAgent();
  agent.disableNetConnect(); // ни одного запроса к настоящему exp.host
  store = new MemoryTokenStore();
  expo = new Expo({ httpAgent: agent });
});

async function withServer(fn: (url: string) => Promise<void>) {
  const server = createPushServer(expo, store).listen(0);
  await new Promise((r) => server.once('listening', r));
  try {
    await fn(`http://127.0.0.1:${(server.address() as AddressInfo).port}`);
  } finally {
    server.close();
  }
}

test('регистрация токена: 401 без пользователя, 400 на мусор, 204 на токен Expo', async () => {
  await withServer(async (url) => {
    const post = (body: unknown, user?: string) =>
      fetch(`${url}/v1/push-tokens`, {
        method: 'POST',
        headers: { 'content-type': 'application/json', ...(user ? { 'x-demo-user': user } : {}) },
        body: JSON.stringify(body),
      });
    assert.equal((await post({ token: TOKEN_A })).status, 401);
    assert.equal((await post({ token: 'not-a-token' }, 'u1')).status, 400);
    assert.equal((await post({ token: TOKEN_A }, 'u1')).status, 204);
    assert.deepEqual(await store.listForUser('u1'), [TOKEN_A]);
  });
});

test('отправка: тикет DeviceNotRegistered удаляет токен, ok попадает в квитанции', async () => {
  await store.save('u1', TOKEN_A);
  await store.save('u1', TOKEN_B);
  let sentBody: Array<Record<string, unknown>> = [];
  agent
    .get('https://exp.host')
    .intercept({ path: '/--/api/v2/push/send', method: 'POST' })
    .reply(200, (opts) => {
      sentBody = JSON.parse(String(opts.body)); // SDK сжимает gzip только большие запросы
      return {
        data: [
          { status: 'ok', id: 'receipt-1' },
          { status: 'error', message: 'not registered', details: { error: 'DeviceNotRegistered' } },
        ],
      };
    });

  await withServer(async (url) => {
    const res = await fetch(`${url}/v1/test-push`, { method: 'POST', headers: { 'x-demo-user': 'u1' } });
    assert.equal(res.status, 202);
    assert.deepEqual(await res.json(), { queued: 1 });
  });
  assert.equal(sentBody.length, 2);
  assert.deepEqual(sentBody[0].data, { url: '/orders/1042' });
  assert.equal(sentBody[0].channelId, 'orders');
  assert.deepEqual(await store.listForUser('u1'), [TOKEN_A]);
});

test('квитанции: DeviceNotRegistered удаляет токен', async () => {
  await store.save('u1', TOKEN_A);
  agent
    .get('https://exp.host')
    .intercept({ path: '/--/api/v2/push/getReceipts', method: 'POST' })
    .reply(200, { data: { 'receipt-1': { status: 'error', details: { error: 'DeviceNotRegistered' } } } });

  const result = await checkReceipts(expo, store, [{ receiptId: 'receipt-1', token: TOKEN_A }]);
  assert.deepEqual(result, { checked: 1, failed: 1 });
  assert.deepEqual(await store.listForUser('u1'), []);
});

$ cd server && npx tsc --noEmit && npm test
✔ регистрация токена: 401 без пользователя, 400 на мусор, 204 на токен Expo (30.1206ms)
✔ отправка: тикет DeviceNotRegistered удаляет токен, ok попадает в квитанции (14.2506ms)
✔ квитанции: DeviceNotRegistered удаляет токен (1.4411ms)
ℹ tests 3
ℹ pass 3
ℹ fail 0
$ cd ../app && npx tsc --noEmit && npx jest
PASS __tests__/notificationNavigation.test.tsx
PASS __tests__/registerForPush.test.ts
Tests:       6 passed, 6 total
$ npx expo export --platform android --platform ios
Android Bundled 6092ms index.ts (643 modules)
iOS Bundled 9340ms index.ts (645 modules)
Exported: dist