مشاركة عبر

دفع تسجيل جهاز الإعلام لمطوري التطبيقات

  • مقالة

لمعرفة المزيد حول الأسلوب الإجمالي لإعداد إعلامات الدفع في Customer Insights - Journeys، قم بزيارة نظرة عامة حول إعداد إعلامات الدفع

لتمكين الإعلامات المؤقتة في Customer Insights - Journeys، يلزمك إكمال الخطوات التالية:

  1. تكوين تطبيق الإشعارات
  2. تعيين المستخدم إعلامات الدفع
  3. تسجيل الجهاز من أجل إعلامات الدفع
  4. تلقي الإخطارات على الأجهزة
  5. إعداد تقارير التفاعل من أجل إعلامات الدفع

يصف هذا المخطط خطوتين ضروريتين لتسجيل الأجهزة والمستخدمين داخل Customer Insights - Journeys.

جهاز دفع الإخطارات ومخطط تسجيل المستخدم.

تسجيل الجهاز

لإكمال تكوين تطبيق الجوال، يجب على المطور تسجيل الأجهزة عبر الخوادم. يجب أن يكون لديك Customer Insights - Journeys بالفعل رمز الجهاز وملف تعريف المستخدم من (ID جهة الاتصال وملف Customer Insights - Data تعريف المستخدم المتوقع وملف تعريف الم ID) وملف تعريف تطبيق الجوال من Customer Insights - Journeys.

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

API

تسجيل الجهاز (فردي)

نموذج طلب HTTP (iOS):

POST {PublicEndpoint}/api/v1.0/orgs/%ORG_ID%/pushdeviceregistration/devices

{
    "MobileAppId": "00000000-0000-0000-0000-000000000000",
    "UserId": "00000000-0000-0000-0000-000000000000",
    "ApiToken": "%API_TOKEN%",
    "ApnsDeviceToken": "%APNS_TOKEN%"
}

نموذج طلب HTTP (Android):

POST {PublicEndpoint}/api/v1.0/orgs/%ORG_ID%/pushdeviceregistration/devices

{
    "MobileAppId": "00000000-0000-0000-0000-000000000000",
    "UserId": "00000000-0000-0000-0000-000000000000",
    "ApiToken": "%API_TOKEN%",
    "FcmDeviceToken": "%FCM_TOKEN%"
}

‏‫الرؤوس‬:

  • x-ms-track-registration: عند تحقق، يتم تخزين المعلومات المتعلقة بنجاح التسجيل/الفشل وتتوفر من خلال API حالة التسجيل.
  • x-ms-callback-url: عندما لا يكون فارغًا، يؤدي تسجيل الجهاز الفاشل أو الناجح إلى تشغيل خطاف الويب لطلب POST.
  • x-ms-callback-url-headers: يحتوي على JSON متسلسل لقاموس سلسلة إلى سلسلة، يمثل الرؤوس التي تم تمريرها لطلبات خطاف الويب. لا يتم استخدامه إلا عند تحديد x-ms-callback-url.

المرتجعات: 202 إذا كان الطلب المقدم صالحًا، و400 بخلاف ذلك.

النص الأساسي للرد:

عند تحقق تسجيل x-ms-track-track :

{
    "RegistrationRequestId": "%GUID%"
}

وإلا، فهى هيئة فارغة.

التعريفات
الاسم الوصف
MobileAppId معرف تطبيق الجوال الذي تم تكوينه في Customer Insights - Journeys.
معرف المستخدم معرف المستخدم الخاص جهة الاتصال أو المتوقع أو ملف Customer Insights - Data التعريف منه Customer Insights - Journeys.
ApiToken رمز API الخاص بك الذي سيتم إرساله إلى الطلب.
ApnsDeviceToken معرف رمز الجهاز الفريد الذي تم إنشاؤه بواسطة تطبيق iOS. سيتم إرسال هذا فقط لجهاز iOS
FcmDeviceToken معرف رمز الجهاز الفريد الذي تم إنشاؤه بواسطة تطبيق Android. سيتم إرسال هذا فقط لجهاز Android

تسجيل الجهاز (متعدد)

يحتوي جسم تسجيل الدفعة على صفيف يصل إلى 100 شيء يمثل طلبات تسجيل الجهاز.

نموذج طلب HTTP (iOS):

POST {PublicEndpoint}/api/v1.0/orgs/%ORG_ID%/pushdeviceregistration/devices/batch

[
    {
        "MobileAppId": "00000000-0000-0000-0000-000000000000",      
        "UserId": "00000000-0000-0000-0000-000000000000",
        "ApiToken": "%API_TOKEN%",
        "ApnsDeviceToken": "%APNS_TOKEN%"
    },
    {
        "MobileAppId": "00000000-0000-0000-0000-000000000000",
        "UserId": "00000000-0000-0000-0000-000000000000",
        "ApiToken": "%API_TOKEN%",
        "ApnsDeviceToken": "%APNS_TOKEN%"
    }
]

نموذج طلب HTTP (Android):

POST {PublicEndpoint}/api/v1.0/orgs/%ORG_ID%/pushdeviceregistration/devices/batch

[
    {
        "MobileAppId": "00000000-0000-0000-0000-000000000000",      
        "UserId": "00000000-0000-0000-0000-000000000000",
        "ApiToken": "%API_TOKEN%",
        "FcmDeviceToken": "%FCM_TOKEN%"
    },
    {
        "MobileAppId": "00000000-0000-0000-0000-000000000000",
        "UserId": "00000000-0000-0000-0000-000000000000",
        "ApiToken": "%API_TOKEN%",
        "FcmDeviceToken": "%FCM_TOKEN%"
    }
]

‏‫الرؤوس‬:

  • x-ms-track-registration: عندما يكون هذا صحيحًا، يتم تخزين المعلومات حول نجاح التسجيل أو فشله وتكون متاحة من خلال واجهة برمجة تطبيقات حالة التسجيل.
  • x-ms-callback-url: عندما لا يكون فارغًا، يؤدي تسجيل الجهاز الفاشل أو الناجح إلى تشغيل رسالة POST طلب الرد التلقائي على الويب.
  • x-ms-callback-url-headers: :يحتوي على JSON متسلسل لقاموس سلسلة إلى سلسلة، يمثل الرؤوس التي تم تمريرها لطلبات خطاف الويب. تستخدم فقط عندما x-ms-callback-url يتم تحديدها.

المرتجعات: 202 إذا كان الطلب المقدم صالحًا، و400 بخلاف ذلك.

النص الأساسي للرد:

عندما يكون تسجيل x-ms-track-registration صحيحا: صفيف من العناصر، يتطابق كل أمر عنصر مع أمر من صفيف جسم الطلب.

[
    {
        "RegistrationRequestId": "%REG_REQUEST_ID%"
    },
    {
        "RegistrationRequestId": "%REG_REQUEST_ID%"
    }
]

وإلا، فهى هيئة فارغة.

حالة تسجيل الجهاز

POST  {PublicEndpoint}/api/v1.0/orgs/%ORG_ID%/pushdeviceregistration/devices/status/

نص الطلب:

{
    "RegistrationRequestIds": [
        "%REG_REQUEST_ID%"
    ],
    "MobileAppId": "%MOBILE_APP_ID%",
    "ApiToken": "%API_TOKEN%"
}

المرتجعات: 200 إذا كان الطلب المقدم صالحًا، و400 إذا كان غير ذلك.

جسم الاستجابة - صفيف العناصر:

[
    {
        "Status": "Pending|Success|Failed",
        "FailureReason": " DuplicateExists|DryRunSendingFailed|DeviceTokenTooLong|FailedToStoreDevice|ApiTokenNotValid " // dry run sending is a verification of device token by sending an invisible notification to mobile app. Such sending failure might happen due to a wrong device token or incorrect/expired mobile app auth data
    },
    {
        "Status": "Pending|Success|Failed",
        "FailureReason": " DuplicateExists|DryRunSendingFailed|DeviceTokenTooLong|FailedToStoreDevice|ApiTokenNotValid " // dry run sending is a verification of device token by sending an invisible notification to mobile app. Such sending failure might happen due to a wrong device token or incorrect/expired mobile app auth data
    }
]

يتطابق كل أمر عنصر مع الأمر من صفيف RegistrationRequestIds .

التعريفات
الاسم الوصف
RegistrationRequestIds صفيف طلبات التسجيل الفردية. يتم أخذ القيم من رد مكالمات التسجيل. لا يتم توفير ذلك إلا عندما يتم استخدام رأس x-ms-track-registration للتسجيل
MobileAppId معرف تطبيق الجوال الذي تم تكوينه في Customer Insights - Journeys.
معرف المستخدم معرف المستخدم الخاص جهة الاتصال أو المتوقع أو ملف Customer Insights - Data التعريف منه Customer Insights - Journeys.

مهم

هناك ثلاثة أسباب محتملة لتتعثر الحالة في حالة "معلق":

  1. كان طلب تسجيل الجهاز الأصلي به رمز API غير صالح. لمنع الحالات المهينة من تنفيذ هجوم DOS على بيئة من خلال الاتصال ب "جهاز التسجيل" وإجراء عمليات الفرز غير المثمرة، لا ينتج عن مثل هذه المحاولات تخزين محفوظات التسجيل. لذلك، لا توجد معلومات للتحقق من النجاح.
  2. يبقى CRM في حالة thro أنثروتكد لعدة ساعات، مما يتسبب في فشل عملية تحديث الحالة في تنفيذ المهمة بعد إعادة المحاولة المتعددة.
  3. تم إجراء طلب تسجيل الجهاز دون توفير رأس تسجيل x-ms-track- .

خطاف ويب لحالة تسجيل الجهاز

إذا تم توفير عنوان URL ل x-ms-status-callback-URL Customer Insights - Journeys عند نجاح تسجيل جهاز أو فشله، في الوصول إلى قيمة العنوان.

نشر إلى عنوان URL المضمن في عنوان x-ms-status-callback-url لطلب تسجيل الجهاز.

النص الأساسي:

{ 
    "Status": "Success|Failed", 
    "Signature": "%SIGNATURE%", 
    "FailureReason": " DuplicateExists|DryRunSendingFailed|DeviceTokenTooLong|FailedToStoreDevice|ApiTokenNotValid" 
}

تلميح

التوقيع هو تجزئة HMACSHA256 لعنوان URL لرد الاتصال المحسوب باستخدام رمز API المميز كمفتاح. استخدم القيمة للتحقق من إدلتك Customer Insights - Journeys على المكالمة. قم بتجزئة عنوان URL لرد الاتصال مع رمز API المميز على جانب خطاف الويب باستخدام نفس الخوارزمية ومقارنة القيم.

‏‫ملاحظة

محاولة تقديم طلب تحدث مرة واحدة. يتسبب أي فشل في تنفيذ طلب في فقدان الإعلام. تتضمن أنواع الفشل عنوان URL غير صحيح للاستدعاء أو واجهة برمجة تطبيقات REST استدعاء غير صحيح أو رمز حالة استجابة غير متوقع.

المرتجعات: 202 إذا كان الطلب المقدم صالحًا، و400 بخلاف ذلك.

الجسم المتوقع : جسد فارغ .

تنظيف الجهاز (فردي):

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

POST {PublicEndpoint}/api/v1.0/orgs/%ORG_ID%/pushdeviceregistration/devices/cleanup

{
    "MobileAppId": "00000000-0000-0000-0000-000000000000",
    "ApiToken": "%API_TOKEN%",
    "UserId": "00000000-0000-0000-0000-000000000000",
    "DeviceToken": "%OPTIONAL_FCM_OR_APNS_DEVICE_TOKEN%"
}

المرتجعات: 202 إذا كان الطلب المقدم صالحًا، و400 بخلاف ذلك.

التعريفات
الاسم الوصف
MobileAppId معرف تطبيق الجوال الذي تم تكوينه في Customer Insights - Journeys.
ApiToken رمز API الخاص بك الذي سيتم إرساله إلى الطلب.
معرف المستخدم معرف المستخدم الخاص جهة الاتصال أو المتوقع أو ملف Customer Insights - Data التعريف منه Customer Insights - Journeys.
DeviceToken معرف رمز الجهاز الفريد الذي تم إنشاؤه بواسطة التطبيق.

تنظيف الجهاز (متعدد)

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

POST {PublicEndpoint}/api/v1.0/orgs/%ORG_ID%/pushdeviceregistration/devices/cleanup/batch

{
    "MobileAppId": "00000000-0000-0000-0000-000000000000",
    "ApiToken": "%API_TOKEN%",
    "UserId": "00000000-0000-0000-0000-000000000000",
    "DeviceToken": "%OPTIONAL_FCM_OR_APNS_DEVICE_TOKEN%"
}

المرتجعات: 202 إذا كان الطلب المقدم صالحًا، و400 بخلاف ذلك.

التعريفات
الاسم الوصف
MobileAppId معرف تطبيق الجوال الذي تم تكوينه في Customer Insights - Journeys.
ApiToken رمز API الخاص بك الذي سيتم إرساله إلى الطلب.
معرف المستخدم معرف المستخدم الخاص جهة الاتصال أو المتوقع أو ملف Customer Insights - Data التعريف منه Customer Insights - Journeys.
DeviceToken معرف رمز الجهاز الفريد الذي تم إنشاؤه بواسطة التطبيق.