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

# Next.js — الإشعارات

> أعِدّ تسليم الإشعارات عبر Web Push القياسي (VAPID) لتطبيق Next.js الخاص بك — بدون Firebase، بدون OneSignal.

## مقدمة

يُرسِل Lerix الإشعارات إلى تطبيقات Next.js باستخدام **بروتوكول Web Push
القياسي (VAPID)** — نفس المعيار المفتوح الذي تطبّقه Chrome وFirefox وEdge
وSafari الحديث أصلياً. بدون مشروع Firebase، بدون حساب OneSignal — يُنشئ
Lerix زوج المفاتيح ويديره نيابةً عنك. بعد إتمام
[تثبيت Next.js](/ar/frameworks/nextjs/installation)، اتّبع الخطوات أدناه
لتفعيل تسليم الإشعارات.

<Note>
  تأكّد من أن تطبيقك مغلّف بـ `LerixNextProvider` قبل إعداد الإشعارات.
</Note>

## 1. انسخ عامل الخدمة (service worker)

يتطلّب Web Push ملف عامل خدمة يُقدَّم من نفس أصل تطبيقك — لا يمكن لحزمة
إضافة هذا الملف إلى تطبيقك تلقائياً. انسخه إلى مجلد `public` الخاص بك
بحيث يكون متاحاً على جذر موقعك:

```bash theme={"dark"}
cp node_modules/@lerix-dev/lerix-core/sw/lerix-sw.js your-app/public/lerix-sw.js
```

## 2. أنشئ مفتاح Web Push

من لوحة التحكم: **الإشعارات ← الإعدادات ← Web Push ← إنشاء المفاتيح**.
هذه خطوة بنقرة واحدة — يُنشئ Lerix زوج مفاتيح VAPID ويخزّنه للمشروع؛
لا حاجة لنسخ أي شيء في كودك.

## 3. اشترك

```tsx theme={"dark"}
'use client';
import { useEffect } from 'react';
import { useLerixNotifications } from '@lerix-dev/lerix-nextjs';

export function MyComponent() {
  const notifications = useLerixNotifications();

  useEffect(() => {
    notifications.setOnNotificationReceived((payload) => {
      // يُستدعى أثناء فتح التبويب.
      console.log(payload.title, payload.body);
    });

    notifications.setOnNotificationTapped((payload) => {
      // يُستدعى عند ضغط المستخدم على الإشعار.
      const screen = payload.metadata['screen'];
    });
  }, []);

  const enablePush = async () => {
    const subscribed = await notifications.subscribe();
  };

  return <button onClick={enablePush}>Enable notifications</button>;
}
```

تطلب `subscribe()` إذن الإشعارات، وتسجّل عامل الخدمة، وتشترك في هذا
المتصفح للإشعارات، وتسجّل الاشتراك لدى الخادم — استدعاء واحد للتدفّق بأكمله.

## البيانات (Payload) المُستلَمة مع الإشعار

```ts theme={"dark"}
interface LerixNotificationPayload {
  notificationId: string | null;
  title: string | null;
  body: string | null;
  metadata: Record<string, unknown>;
  imageUrl: string | null;
}
```

## معرّفات الجهاز

| الدالة | ترجع | استخدمها من أجل |
| - | - | - |
| `getRegisteredTokenId()` | معرّف Lerix الخاص بهذا الجهاز المُسجَّل | القيمة التي تضعها في حقل استهداف الجهاز في لوحة التحكم/REST API |
| `getDeviceToken()` | كائن `PushSubscription` الأصلي، مُحوَّل إلى نص | نادراً ما تحتاجه مباشرة؛ للتشخيص فقط |
| `getDeviceId()` | معرّف مُولَّد محلياً، لا علاقة له بالباك إند الخاص بـ Lerix | للتشخيص المحلي فقط؛ **ليس** ما تتوقّعه عملية الإرسال من لوحة التحكم |

```tsx theme={"dark"}
const tokenId = notifications.getRegisteredTokenId();
```

ترجع الدوال الثلاث جميعها `null` حتى تكتمل `subscribe()` مرة واحدة على الأقل.

## إرسال بيانات وصفية (Metadata)

```json theme={"dark"}
{
  "title": "New message from John",
  "body": "Hey, are you free later?",
  "metadata": { "chatId": "456", "screen": "chat" }
}
```

```tsx theme={"dark"}
notifications.setOnNotificationTapped((payload) => {
  const chatId = payload.metadata['chatId'];
});
```

## إرسال صورة

اضبط `imageUrl` عند الإرسال. يعمل هذا تلقائياً دون أي إعداد إضافي: يعرض
عامل الخدمة الصورة مباشرة كأيقونة/صورة الإشعار.

<Note>
  **الصوت المخصّص غير مدعوم في إشعارات الويب.** لا تتيح واجهة Web
  Notifications API طريقة لضبط صوت إشعار مخصّص عبر المتصفحات — ينطبق
  معامل `sound` فقط على iOS وAndroid.
</Note>

## استهدف مستخدماً على كل أجهزته

إذا كان منتجك يعمل أيضاً على منصات أخرى (الويب أو الجوال أو سطح المكتب)،
فأضِفها إلى نفس المشروع واربط كل تثبيت بمعرّف المستخدم الخاص بك بعد تسجيل
الدخول. عندها يستطيع الباك إند الخاص بك الإرسال إلى `externalUserIds` والوصول
إلى هذا الشخص على كل أجهزته في طلب واحد.

```tsx theme={"dark"}
import { useLerix } from '@lerix-dev/lerix-nextjs';

const lerix = useLerix(); // inside a component

await lerix.setUser('user_123'); // after login
await lerix.clearUser();         // on logout
```

راجع [تعريف المستخدمين](/ar/modules/users-identity) للتحقق من الهوية ومثال
على الإرسال.

## المواضيع (Topics)

```tsx theme={"dark"}
await notifications.subscribeToTopic('promotions');
await notifications.unsubscribeFromTopic('promotions');
```

للإرسال إلى موضوع، استخدم تبويب **إرسال إشعار** في لوحة التحكم (اختر
"Topic" كجمهور مستهدف)، أو استدعِ
[REST API](/ar/api-reference/push-notifications) مع `sendByTopic: true`.

## دعم المتصفحات

تدعم Chrome وFirefox وEdge خدمة Web Push بشكل كامل. يتطلّب Safari macOS
13+‎ أو iOS 16.4+‎ — إصدارات Safari الأقدم لا تدعم المعيار إطلاقاً.


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