انتقل إلى المحتوى
أدلة المستخدمالدعم طلب عرض توضيحي تسجيل الدخول
Pushwoosh.com

Web push SDK 3.0

الدمج

Anchor link to

نموذج دمج على GitHub

احصل على Pushwoosh Web Push SDK وقم بفك ضغطه. يجب أن يكون لديك الملفات التالية:

Anchor link to
  • pushwoosh-service-worker.js

ضع كل هذه الملفات في الدليل الجذري لموقع الويب الخاص بك.

Anchor link to

تهيئة SDK:

Anchor link to
  1. قم بتضمين SDK من شبكة توصيل المحتوى (CDN) الخاصة بنا بشكل غير متزامن.
<script type="text/javascript" src="//cdn.pushwoosh.com/webpush/v3/pushwoosh-web-notifications.js" async></script>
  1. قم بتهيئة Web Push SDK وتأكد من وضع التهيئة في قائمة الانتظار حتى يتم تحميل SDK بالكامل.
<script type="text/javascript">
var Pushwoosh = Pushwoosh || [];
Pushwoosh.push(['init', {
    logLevel: 'info', // القيم الممكنة: error, info, debug
    applicationCode: 'XXXXX-XXXXX', // رمز التطبيق الخاص بك من لوحة تحكم Pushwoosh
    apiToken: 'XXXXXXX', //  Device API Token
    safariWebsitePushID: 'web.com.example.domain', //  سلسلة نطاق عكسي فريدة، يتم الحصول عليها من بوابة مطوري Apple. مطلوبة فقط إذا كنت ترسل إشعارات دفع إلى متصفح Safari
    defaultNotificationTitle: 'Pushwoosh', // يحدد عنوانًا افتراضيًا لإشعارات الدفع
    defaultNotificationImage: 'https://yoursite.com/img/logo-medium.png', // عنوان URL لصورة إشعار مخصصة
    autoSubscribe: false, // أو true. إذا كانت القيمة true، فإنه يطالب المستخدم بالاشتراك في الإشعارات عند تهيئة SDK
    subscribeWidget: {
      enable: true
    },
    userId: 'user_id', // اختياري، قم بتعيين User ID مخصص
    tags: {
        'Name': 'John Smith'     // اختياري، قم بتعيين Tags مخصصة
    }
}]);
</script>

النوافذ المنبثقة للويب

Anchor link to

أضف webPopups إلى كائن init الخاص بك لتمكين حملات النوافذ المنبثقة للويب على موقعك.

webPopups: {
  enable: true,
},

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

زر الاشتراك في الإشعارات

Anchor link to

لحث المستخدمين على الاشتراك في إشعارات الدفع، نوصي بتنفيذ زر الاشتراك في الإشعارات على موقع الويب الخاص بك. عزز تجربة المستخدم واحصل على المزيد من المشتركين!

التكوين

Anchor link to

لإنهاء تنفيذ إشعارات الدفع في موقع الويب الخاص بك، تحتاج إلى تكوين منصات الويب في لوحة تحكم Pushwoosh الخاصة بك باتباع أدلتنا خطوة بخطوة:

تسجيل service worker في نطاق مختلف

Anchor link to

في بعض الأحيان لا يمكنك وضع ملف service worker في الدليل الجذري لموقع الويب ولكن في دليل فرعي.

في هذه الحالة، قم بتعديل التكوين (الخطوة 4.3) بإضافة معلمة

serviceWorkerUrl: “/push-notifications/pushwoosh-service-worker.js”

حيث /push-notifications/pushwoosh-service-worker.js هو المسار إلى ملف pushwoosh-service-worker.js.

معالجات الأحداث

Anchor link to

في Pushwoosh Web SDK 3.0 يمكنك الاشتراك في أحداث معينة لتتبعها**،** أو إلغاء الاشتراك من الأحداث إذا لم تعد بحاجة إلى تتبعها.

لتتبع تحميل Web SDK 3.0، قم بتشغيل حدث onLoad كما يلي:

// Load Event
Pushwoosh.push(['onLoad', (api) => {
  console.log('Pushwoosh load!');
}]);

لتتبع التهيئة الصحيحة لـ Web SDK، قم بتشغيل حدث onReady:

// Ready Event
Pushwoosh.push((api) => {
  console.log('Pushwoosh ready!');
});

للاشتراك في أي من أحداث SDK أو إلغاء الاشتراك منها، استخدم المعالجات بعد تحميل SDK:

Pushwoosh.push(['onLoad', (api) => {
  function onEventNameHandler() {
    console.log('Triggered event: event-name!');
  }


  // To subscribe to an event:
  Pushwoosh.addEventHandler('event-name', onEventNameHandler)


  // To unsubscribe from an event:
  Pushwoosh.removeEventHandler('event-name', onEventNameHandler)
}]);

أحداث SDK

Anchor link to

حدث الاشتراك (subscribe)

Anchor link to

يتم تنفيذه بعد موافقة المستخدم على تلقي إشعارات الدفع.

Pushwoosh.push(['onLoad', (api) => {
  Pushwoosh.addEventHandler('subscribe', (payload) => {
    console.log('Triggered event: subscribe');
  });
}]);

حدث إلغاء الاشتراك (unsubscribe)

Anchor link to

يتم تنفيذه بعد إلغاء تسجيل جهاز من الإشعارات.

Pushwoosh.push(['onLoad', (api) => {
  Pushwoosh.addEventHandler('unsubscribe', (payload) => {
    console.log('Triggered event: unsubscribe');
  });
}]);

أحداث أداة الاشتراك

Anchor link to

تتبع عرض أداة طلب الاشتراك.

Pushwoosh.push(['onLoad', (api) => {
  // يتم تنفيذه عند عرض أداة طلب الاشتراك
  Pushwoosh.addEventHandler('show-subscription-widget', (payload) => {
    console.log('Triggered event: show-subscription-widget');
  });


  // يتم تنفيذه عند إخفاء أداة طلب الاشتراك
  Pushwoosh.addEventHandler('hide-subscription-widget', (payload) => {
    console.log('Triggered event: hide-subscription-widget');
  });
}]);

أحداث مربع حوار إذن الإشعارات

Anchor link to

تتبع عرض مربع حوار الاشتراك الأصلي.

Pushwoosh.push(['onLoad', function (api) {
  // يتم تنفيذه عند عرض مربع حوار الإذن
  Pushwoosh.addEventHandler('show-notification-permission-dialog', (payload) => {
    console.log('Triggered event: show-notification-permission-dialog');
  });


  // يتم تنفيذه عند إخفاء مربع حوار الإذن بإحدى الحالات الثلاث الممكنة:
  // 1. default - تم إغلاق مربع الحوار
  // 2. granted - تم منح الإذن
  // 3. denied - تم رفض الإذن
  Pushwoosh.addEventHandler('hide-notification-permission-dialog', (payload) => {
    console.log('Triggered event: hide-notification-permission-dialog', payload.permission);
  });
}]);

أحداث الإذن

Anchor link to

تحقق من حالة إذن إشعارات الدفع عند تهيئة SDK؛ تتبع تحديث هذه الحالة كلما حدث.

Pushwoosh.push(['onLoad', (api) => {
  // يتم تنفيذه أثناء تهيئة SDK إذا كانت 'autoSubscribe: false' و/أو إذا تجاهل المستخدم طلب إشعار الدفع.
  Pushwoosh.addEventHandler('permission-default', (payload) => {
    console.log('Triggered event: permission-default');
  });


  // يتم تنفيذه أثناء تهيئة SDK إذا تم حظر الإشعارات أو بمجرد أن يحظر المستخدم إشعارات الدفع.
  Pushwoosh.addEventHandler('permission-denied', (payload) => {
    console.log('Triggered event: permission-denied');
  });


  // يتم تنفيذه أثناء تهيئة SDK إذا تم السماح بالإشعارات أو بمجرد أن يسمح المستخدم بإشعارات الدفع.
  Pushwoosh.addEventHandler('permission-granted', (payload) => {
    console.log('Triggered event: permission-granted');
  });
}]);

حدث استلام الإشعار (receive-push)

Anchor link to

تتبع تسليم الإشعار إلى جهاز.

Pushwoosh.push(['onLoad', (api) => {
  // يتم تنفيذه عند عرض إشعار دفع.
  Pushwoosh.addEventHandler('receive-push', (payload) => {
    console.log('Triggered event: receive-push', payload.notification);
  });
}]);

أحداث الإشعارات

Anchor link to

تتبع ما إذا كان المستخدم قد فتح إشعار دفع أم أغلقه.

Pushwoosh.push(['onLoad', (api) => {
  // يتم تنفيذه عندما ينقر المستخدم على الإشعار.
  Pushwoosh.addEventHandler('open-notification', (payload) => {
    console.log('Triggered event: open-notification', payload.notification);
  });


  // يتم تنفيذه عندما يغلق المستخدم إشعار دفع.
  Pushwoosh.addEventHandler('hide-notification', (payload) => {
    console.log('Triggered event: hide-notification', payload.notification);
  });
}]);

أحداث صندوق الوارد (Inbox)

Anchor link to

تتبع الإشعارات المرسلة إلى صندوق الوارد.

Pushwoosh.push(['onLoad', (api) => {
  // يتم تنفيذه بواسطة ServiceWorker بعد استلام رسالة صندوق الوارد وحفظها في indexedDB.
  Pushwoosh.addEventHandler('receive-inbox-message', (payload) => {
    console.log('Triggered event: receive-inbox-message', payload.message);
  });


  // يتم تنفيذه بعد تحديث صندوق الوارد تلقائيًا أثناء تحميل الصفحة.
  Pushwoosh.addEventHandler('update-inbox-messages', (payload) => {
    console.log('Triggered event: receive-inbox-message', payload.messages);
  });
}]);

أحداث النافذة المنبثقة للاشتراك المخصصة

Anchor link to

للحصول على تفاصيل حول معالجة أحداث النافذة المنبثقة للاشتراك المخصصة، يرجى الرجوع إلى دليل أحداث النافذة المنبثقة للاشتراك المخصصة.

واجهة برمجة التطبيقات (API)

Anchor link to

بعد تهيئة Web Push SDK، يمكنك إجراء الاستدعاءات التالية إلى Pushwoosh API. جميع الدوال تعيد كائنات Promise.

Pushwoosh.push((api) => {
  // تعيين Tags لمستخدم
  api.setTags({
    'Tag Name 1': 'value1',
    'Tag Name 2': 'value2'
  });


  // الحصول على Tags لمستخدم من الخادم
  api.getTags();


  // تسجيل User ID
  api.registerUser('user123');


    // تسجيل البريد الإلكتروني للمستخدم
  api.registerEmail('user@example.com');


  // تسجيل رقم SMS
  api.registerSmsNumber('+15551234567');


  // تسجيل رقم WhatsApp
  api.registerWhatsappNumber('+1234567890');


  // نشر حدث (Event)
  api.postEvent('myEventName', {attributeName: 'attributeValue'});


  // إلغاء التسجيل من الإشعارات
  api.unregisterDevice();


  // تعيين لغة الجهاز (يتجاوز القيمة في "Language" Tag)
  api.setLanguage('es');


  // بدلاً من ذلك، تسجيل متعدد للمستخدم مع الأجهزة والقنوات
  api.multiRegisterDevice({
    user_id: 'user123',
    email: 'user@example.com',
    sms_phone_number: '+1234567890',
    tags: {
      'UserType': { operation: TTagOperationSet, value: 'Premium' },
      'Interests': { operation: TTagOperationAppend, values: ['sports', 'technology'] }
    }
  });
});

multiRegisterDevice

Anchor link to

طريقة تسجيل محسنة تسمح بتسجيل ملف تعريف مستخدم مع أجهزة وقنوات مراسلة متعددة في استدعاء API واحد. هذه الطريقة مفيدة بشكل خاص للتطبيقات متعددة المنصات أو عند تنفيذ استراتيجيات المراسلة متعددة القنوات.

Pushwoosh.push((api) => {
  api.multiRegisterDevice({
    user_id: 'user123',              // اختياري: معرف المستخدم
    email: 'user@example.com',       // اختياري: البريد الإلكتروني للمراسلة عبر البريد الإلكتروني
    sms_phone_number: '+1234567890', // اختياري: رقم هاتف SMS (تنسيق E.164)
    whatsapp_phone_number: '+1234567890', // اختياري: رقم WhatsApp (تنسيق E.164)
    kakao_phone_number: '+1234567890',    // اختياري: رقم KakaoTalk (تنسيق E.164)
    language: 'en',                  // اختياري: رمز اللغة (ISO 639-1)
    timezone: 'America/New_York',    // اختياري: معرف المنطقة الزمنية
    city: 'New York',               // اختياري: المدينة للاستهداف
    country: 'US',                  // اختياري: البلد للاستهداف
    state: 'NY',                    // اختياري: الولاية للاستهداف
    tags: {                         // اختياري: قيم Tag مع العمليات
      'UserType': {
        operation: TTagOperationSet,     // تعيين قيمة Tag (0)
        value: 'Premium'
      },
      'Interests': {
        operation: TTagOperationAppend,  // إلحاق بقيمة Tag (1)
        values: ['sports', 'technology']
      },
      'LoginCount': {
        operation: TTagOperationIncrement, // زيادة قيمة Tag (3)
        value: '1'
      }
    },
    push_devices: [                 // اختياري: مصفوفة من أجهزة الدفع
      {
        hwid: 'web-device-456',
        platform: TPlatformChrome, // منصة Chrome (11)
        push_token: 'fcm-token-here',
        app_version: '2.1.0',
        platformData: {
          public_key: 'web-push-public-key',
          auth_token: 'web-push-auth-token',
          browser: 'chrome'
        }
      }
    ]
  })
  .then((response) => {
    console.log('Multi-registration successful:', response);
  })
  .catch((error) => {
    console.error('Multi-registration failed:', error);
  });
});

أنواع المنصات:

  • TPlatformSafari (10): منصة Safari
  • TPlatformChrome (11): منصة Chrome
  • TPlatformFirefox (12): منصة Firefox

أنواع عمليات Tag:

  • TTagOperationSet (0): تعيين قيمة Tag (استبدال القيمة الحالية)
  • TTagOperationAppend (1): إلحاق بقيمة Tag (إضافة إلى قائمة)
  • TTagOperationRemove (2): إزالة قيمة Tag (إزالة من قائمة)
  • TTagOperationIncrement (3): زيادة قيمة Tag (زيادة رقمية)

الفوائد:

  • استدعاء API واحد: تسجيل أجهزة وقنوات متعددة في وقت واحد
  • عملية ذرية: تنجح جميع التسجيلات أو تفشل معًا
  • مرتكز على المستخدم: يربط جميع الأجهزة بملف تعريف مستخدم واحد
  • تمييز متقدم: يدعم عمليات Tag المعقدة
  • متعدد المنصات: التعامل مع منصات متعددة في وقت واحد

مثال على إرسال Tags إلى Pushwoosh:

Pushwoosh.push((api) => {
  var myCustomTags = {
    'Tag 1': 123,
    'Tag 2': 'some string'
  };
  api.setTags(myCustomTags)
    .then((res) => {
      var skipped = res && res.skipped || [];
      if (!skipped.length) {
        console.log('success');
      }
      else {
        console.warn('skipped tags:', skipped);
      }
    })
    .catch((err) => {
      console.error('setTags error:', err);
    });
});

زيادة قيمة Tag

Anchor link to

لزيادة قيمة لـ Number Tag، استخدم المعلمة operation مع القيمة ‘increment’ كما يلي:

Pushwoosh.push((api) => {
  api.setTags({
    'Tag 1': {
      operation: 'increment',
      value: 1
    }
  })
});

إلحاق قيم Tag

Anchor link to

لإلحاق قيم جديدة بـ List Tag الحالي، استخدم المعلمة operation مع القيمة ‘append’ كما يلي:

Pushwoosh.push((api) => {
  api.setTags({
    'Tag 3': {
      operation: 'append',
      value: ['Value3']
    }
  })
});

إزالة قيمة Tag

Anchor link to

لإزالة قيمة من List Tag، استخدم المعلمة operation مع القيمة ‘remove’ كما يلي:

Pushwoosh.push((api) =>{
  api.setTags({
    'Tag 3': {
      operation: 'remove',
      value: ['Value2']
    }
  })
});

الدوال العامة

Anchor link to

Pushwoosh.subscribe()

تُستخدم هذه الدالة لطلب إذن المستخدم لإشعارات الدفع. إذا كان المستخدم مشتركًا بالفعل، ستتوقف الدالة عن التنفيذ.

إذا لم يكن المستخدم قد اشترك في الإشعارات بعد:

  1. يتم طلب الإذن لإشعارات الدفع.
  1. إذا سمح المستخدم بالإشعارات، يتم تشغيل حدث onSubscribe.

يتم تنفيذ Pushwoosh.subscribe() تلقائيًا إذا تم تعيين autoSubscribe: true. أثناء تهيئة SDK.

استدعِ هذه الدالة إذا اخترت مطالبة المستخدم يدويًا بالاشتراك في الإشعارات باستخدام المعلمة autoSubscribe: false أثناء التهيئة:

<button onclick="Pushwoosh.subscribe()">Subscribe</button>
<script>
  Pushwoosh.push(['onSubscribe', (api) => {
    console.log('User successfully subscribed');
  }]);
</script>

Pushwoosh.unsubscribe()

  1. يتم تنفيذ دالة /unregisterDevice.
  2. يتم تشغيل حدث onUnsubscribe.
<button onclick="Pushwoosh.unsubscribe()">Unsubscribe</button>
<script type="text/javascript">
  Pushwoosh.push(['onUnsubscribe', (api) => {
    console.log('User successfully unsubscribed');
  }]);
</script>

Pushwoosh.isSubscribed()

يتحقق مما إذا كان المستخدم مشتركًا ويعيد علامة true/false.

Pushwoosh.isSubscribed().then((isSubscribed) => {
  console.log('isSubscribed', isSubscribed);
});

Pushwoosh.getHWID()

يعيد Pushwoosh HWID.

Pushwoosh.getHWID().then((hwid) => {
  console.log('hwid:', hwid);
});

Pushwoosh.getPushToken()

يعيد رمز الدفع (push token) إذا كان متاحًا.

Pushwoosh.getPushToken().then((pushToken) => {
  console.log('pushToken:', pushToken);
});

Pushwoosh.getUserId()

يعيد User ID إذا كان متاحًا.

Pushwoosh.getUserId().then((userId) => {
  console.log('userId:', userId);
});

Pushwoosh.getParams()

يعيد قائمة بالمعلمات التالية:

Pushwoosh.getParams().then((params) => {
  params = params || {};
  var hwid = params.hwid;
  var pushToken = params.pushToken;
  var userId = params.userId;
});

Pushwoosh.isAvailableNotifications()

يتحقق مما إذا كان المتصفح يدعم Pushwoosh WebSDK 3.0، ويعيد ‘true’ أو ‘false’.

Pushwoosh.isAvailableNotifications() // true/false

دوال InboxMessages

Anchor link to

messagesWithNoActionPerformedCount(): Promise<number>

يعيد عدد الرسائل المفتوحة.

Pushwoosh.pwinbox.messagesWithNoActionPerformedCount()
  .then((count) => {
    console.log(`${count} messages opened`);
  });

unreadMessagesCount()

يعيد عدد الرسائل غير المقروءة.

Pushwoosh.pwinbox.unreadMessagesCount()
  .then((count) => {
    console.log(`${count} messages unread`);
  });

messagesCount(): Promise<number>

يعيد العدد الإجمالي للرسائل.

Pushwoosh.pwinbox.messagesCount()
  .then((count) => {
    console.log(`${count} messages`);
  });

loadMessages(): Promise<Array>

يقوم بتحميل قائمة الرسائل غير المحذوفة.

Pushwoosh.pwinbox.loadMessages()
  .then(() => {
    console.log('Messages have been loaded');
  });

readMessagesWithCodes(codes: Array<string>): Promise<void>

يضع علامة على الرسائل كمقروءة بواسطة Inbox_Ids.

Pushwoosh.pwinbox.readMessagesWithCodes(codes)
  .then(() => {
    console.log('Messages have been read');
  });

performActionForMessageWithCode(code: string): Promise<void>

ينفذ الإجراء المخصص لرسالة ويضع علامة على الرسالة كمقروءة.

Pushwoosh.pwinbox.performActionForMessageWithCode(code)
  .then(() => {
    console.log('Action has been performed');
  });

deleteMessagesWithCodes(codes: Array<string>): Promise<void>

يضع علامة على الرسائل كمحذوفة.

Pushwoosh.pwinbox.deleteMessagesWithCodes([code])
  .then(() => {
    console.log('Messages have been deleted');
  });

syncMessages(): Promise<void>

يزامن الرسائل مع الخادم.

Pushwoosh.pwinbox.syncMessages()
  .then(() => {
    console.log('Messages have been synchronized');
  });

دعم تطبيقات الويب التقدمية (PWA)

Anchor link to

لدمج Pushwoosh في تطبيق الويب التقدمي (PWA) الخاص بك، اتبع الخطوات الموضحة أدناه.

1. انسخ المسار إلى ملف Service Worker الخاص بك:

if ('serviceWorker' in navigator) {
  window.addEventListener('load', () => {
    navigator.serviceWorker.register('/service-worker.js') // <- عنوان url لـ service worker الخاص بك
  });
}

بعد ذلك، استخدم المعلمة serviceWorkerUrl أثناء تهيئة WebSDK كما يلي:

var Pushwoosh = Pushwoosh || [];
Pushwoosh.push(['init', {
  logLevel: 'error',
  applicationCode: 'XXXXX-XXXXX',
  safariWebsitePushID: 'web.com.example.domain',
  defaultNotificationTitle: 'Pushwoosh',
  defaultNotificationImage: 'https://yoursite.com/img/logo-medium.png',
  serviceWorkerUrl: '/service-worker.js', // <- عنوان url لـ service worker الخاص بك
}]);

لا يقوم WebSDK بتسجيل Service Worker الجديد على الفور؛ يتم تسجيل Service Worker عند الحاجة إليه:

  • عندما يتلقى جهاز رمز دفع (عند تسجيل الجهاز أو إعادة الاشتراك)،
  • عندما يتم حذف رمز دفع (عند إزالة جهاز من قاعدة المستخدمين).

إنه يسرع تحميل صفحاتك عن طريق تقليل عدد طلبات الخادم.

لا تسمح المتصفحات بتسجيل اثنين من Service Workers مختلفين في نفس الوقت (اقرأ المزيد: https://github.com/w3c/ServiceWorker/issues/921)، لذلك لكي يعمل PWA الخاص بك بشكل صحيح، يجب تسجيل Service Worker مشترك لقاعدة التعليمات البرمجية الخاصة بك وقاعدة التعليمات البرمجية لـ Pushwoosh.

2. أضف السلسلة التالية إلى Service Worker الخاص بك (في البداية أو في النهاية، لا يهم):

importScripts('https://cdn.pushwoosh.com/webpush/v3/pushwoosh-service-worker.js' + self.location.search);

وبالتالي فإنك تمكن Service Worker الخاص بك من استقبال ومعالجة إشعارات الدفع المرسلة عبر خدمات Pushwoosh.

التثبيت من Google Tag Manager

Anchor link to

استخدم الكود التالي في Google Tag Manager لتهيئة Pushwoosh SDK. قم بإنشاء علامة HTML مخصصة والصق الكود أدناه. تأكد من تغيير Pushwoosh Application Code و Safari Website ID وعنوان URL لصورة الإشعار الافتراضية.
أيضًا، قم بتعيين أولوية إطلاق العلامة عالية (على سبيل المثال: 100) وقم بتشغيلها على جميع الصفحات. انظر لقطة الشاشة أدناه.نسخ

<script type="text/javascript" src="//cdn.pushwoosh.com/webpush/v3/pushwoosh-web-notifications.js" async></script>
<script type="text/javascript">
  var Pushwoosh = Pushwoosh || [];
  Pushwoosh.push(['init', {
    logLevel: 'error',
    applicationCode: 'XXXXX-XXXXX',
    safariWebsitePushID: 'web.com.example.domain',
    defaultNotificationTitle: 'Pushwoosh',
    defaultNotificationImage: 'https://yoursite.com/img/logo-medium.png',
    autoSubscribe: true,
    subscribeWidget: {
      enable: false
    },
    userId: 'user_id'
  }]);
</script>