إرسال أحداث بلا اتصال باستخدام واجهة API التحويلات

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

المتطلبات الأساسية

مجموعة البيانات

يجب أن تكون أحداث التحويل بلا اتصال المرسلة عبر واجهة API التحويلات مرتبطة بمجموعة بيانات.

Datasets allow advertisers to connect and manage event data from web, app, store and business messaging event sources to the Conversions API. Datasets may show event data from any of these integrations that you choose to set up:

Meta Pixel (website events)
App Events API (app events, including Facebook SDK for iOS or Android, mobile measurement partners (MMPs))
Offline Conversions API (Meta’s legacy API for offline events)
Messaging Events API (messaging events)

Datasets enable you to view all customer activities from a single interface. They also allow you to reduce the effort to build and maintain multiple API integrations.

In Events Manager, advertisers have different options to create a dataset depending on their starting point. Or you can create a brand new dataset in Events Manager by linking during offline event set creation or through an existing mobile app or during messaging event set creation information. Note that linking a dataset to an application is required before sending mobile app events to the Conversions API and only one application can be linked to a dataset. See more details and instructions here.

يمكنك إرسال استدعاء GET إلى https://graph.facebook.com/v16.0/{ads-pixel-id}/?fields=is_consolidated_container لاكتشاف ما إذا كانت مجموعة بيانات المعلن مدمجة وبالتالي مؤهلة لإرسال الأحداث بلا اتصال باستخدام واجهة API التحويلات.

الأذونات

لتنفيذ دمج مباشر كمعلن، يرجى اتباع التعليمات هنا للحصول على المتطلبات والأذونات.
لتنفيذ دمج المنصة الشريكة، يرجى اتباع التعليمات هنا لمعرفة المتطلبات والأذونات.

التكوين

1. إعداد معلمات أحداث التحويل بلا اتصال

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

يحتاج المعلنون إلى إرسال action_source كـ physical_store لجميع أحداث المتجر والأحداث بلات اتصال. لاحظ أن هذه المعلمة مطلوبة لجميع أنواع أحداث الخادم. بمجرد استخدام واجهة API التحويلات، فإنك توافق على أن المعلمة action_source دقيقة حسب معلوماتك.
يجب الالتزام بجميع حقول أحداث الخادم في واجهة API التحويلات.
معلمات معلومات العملاء (راجع أدناه للحصول على قائمة مناسبة بمعلمات أحداث المتجر والأحداث بلا اتصال).
معلمات البيانات المخصصة (راجع أدناه للحصول على قائمة مناسبة بمعلمات أحداث المتجر والأحداث بلا اتصال).
المعلمة الاختيارية: لا تزال المعلمة upload_tag مدعومة لتحميل أحداث التحويل بلا اتصال للمعلنين الذين يستخدمون API القديمة لأحداث التحويل بلا اتصال.

معلمات معلومات العملاء

تحتوي القائمة التالية على معلمات معلومات العملاء التي يتم استخدامها عادةً لأحداث التحويل بلا اتصال وأحداث المتجر:

أسماء المعلمات	المعلمة	التجزئة مطلوبة
عنوان (عناوين) البريد الإلكتروني	`email`	نعم
رقم (أرقام) الهاتف	`phone`	نعم
الجنس	`gen`	نعم
تاريخ الميلاد	`db`	نعم
اسم العائلة	`ln`	نعم
الاسم الأول	`fn`	نعم
المدينة	`ct`	نعم
الولايات في الولايات المتحدة	`st`	نعم
الرموز البريدية	`zip`	نعم
البلد	`country`	نعم
معرف إعلانات Apple	`madid`	نعم
معرف إعلانات Android	`madid`	نعم
معرف مستخدم تابع لجهة خارجية	`external_id`	موصى به بشدة
معرف بيانات العميل المحتمل من إعلانات تجميع بيانات العملاء المحتملين	`lead_id`	بدون تجزئة

معلمات البيانات المخصصة

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

المعلمة الوصف

المعلمة	الوصف
`event_time` النوع: integer (عدد صحيح)	مطلوب طابع زمني بتنسيق UNIX لحدث التحويل. مثال: `'1456870055'`
`event_name` النوع: string (سلسلة)	مطلوب نوع الحدث. مثال: `ViewContent, Search, AddToCart, AddToWishlist, InitiateCheckout, AddPaymentInfo, Purchase, Lead, Other`
`store_data` النوع: JSON dictionary (قاموس JSON)	اختياري تخزين بيانات الموقع حول حدث التحويل. المثال: "store_data": { "store_page_id": 8576093908, // FBID "brand_page_id": 10236898932// FBID }
`currency` النوع: string (سلسلة)	مطلوب رمز العملة بتنسيق ISO مكوّن من ثلاثة أحرف لحدث التحويل هذا. يلزم توفيرها لأحداث `Purchase`. مثال: `USD`
`value` النوع: double (قيمة مزدوجة)	مطلوب قيمة حدث التحويل. يلزم توفيرها لأحداث `Purchase`. مثال: `16.00`
`content_type` النوع: string (سلسلة)	اختياري أي إعلانات كتالوج Advantage+ `content_type`صالحة. مثال: `product`
`contents` النوع: JSON array (مصفوفة بلغة JSON)	اختياري. مطلوب في حالة دمج الإعلانات مع الكتالوج. مطلوب: `id`، `quantity` موصى به: `price`، `brand`، `category` مطلوب: `[ {id: "A", quantity: 1}, {id: "B", quantity: 2}, {id: "C", quantity: 1}]` موصى به: `[ {id: "A", quantity: 1, brand: "Brand_A", category: "", price: 10.0}]`
`custom_data` النوع: JSON dictionary (قاموس بلغة JSON)	اختياري. يمثل معلومات حول حدث التحويل هذا. المثال: `{category: 'ICECREAM'}`
`order_id` النوع: string (سلسلة)	اختياري. يمثل معرفًا فريدًا لكل معاملة أو طلب في مجموعة أحداث تحويل بلا اتصال. فعلى سبيل المثال، يمكن أن يمثل معرف إيصال في حالة البيع بالتجزئة. المثال: `ATN10001` و`123456`
`item_number` النوع: string (سلسلة)	اختياري. يمثل معرفًا فريدًا لتمييز الأحداث داخل الطلب نفسه أو المعاملة نفسها. المثال: `1` و`a`

event_time

النوع: integer (عدد صحيح)

مطلوب

طابع زمني بتنسيق UNIX لحدث التحويل.

مثال:
'1456870055'

event_name
النوع: string (سلسلة)

مطلوب

نوع الحدث.

مثال:
ViewContent, Search, AddToCart, AddToWishlist, InitiateCheckout, AddPaymentInfo, Purchase, Lead, Other

store_data
النوع: JSON dictionary (قاموس JSON)

اختياري

تخزين بيانات الموقع حول حدث التحويل.

المثال:

"store_data":
    {
        "store_page_id": 8576093908, // FBID
        "brand_page_id": 10236898932// FBID
    }

currency
النوع: string (سلسلة)

مطلوب

رمز العملة بتنسيق ISO مكوّن من ثلاثة أحرف لحدث التحويل هذا. يلزم توفيرها لأحداث Purchase.

مثال:
USD

value
النوع: double (قيمة مزدوجة)

مطلوب

قيمة حدث التحويل. يلزم توفيرها لأحداث Purchase.

مثال:
16.00

content_type النوع: string (سلسلة)

اختياري

أي إعلانات كتالوج Advantage+ content_typeصالحة.

مثال:
product

contents

النوع: JSON array (مصفوفة بلغة JSON)

اختياري. مطلوب في حالة دمج الإعلانات مع الكتالوج.

مطلوب: id، quantity

موصى به: price، brand، category

مطلوب: [ {id: "A", quantity: 1}, {id: "B", quantity: 2}, {id: "C", quantity: 1}]

موصى به: [ {id: "A", quantity: 1, brand: "Brand_A", category: "", price: 10.0}]

custom_data

النوع: JSON dictionary (قاموس بلغة JSON)

اختياري.

يمثل معلومات حول حدث التحويل هذا.

المثال: {category: 'ICECREAM'}

order_id

النوع: string (سلسلة)

اختياري.

يمثل معرفًا فريدًا لكل معاملة أو طلب في مجموعة أحداث تحويل بلا اتصال. فعلى سبيل المثال، يمكن أن يمثل معرف إيصال في حالة البيع بالتجزئة.

المثال: ATN10001 و123456

item_number

النوع: string (سلسلة)

اختياري.

يمثل معرفًا فريدًا لتمييز الأحداث داخل الطلب نفسه أو المعاملة نفسها.

المثال: 1 وa

2. إرسال الأحداث

لإرسال أحداث جديدة، أرسل طلب POST إلى واجهة API التحويلات من هذا المسار: https://graph.facebook.com/{API_VERSION}/{DATASET_ID}/events?access_token={TOKEN}

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

فيما يلي نظرة عامة على كيفية توافق المعلمات مع المخطط العام في حمولة البيانات:

curl -X POST \
  -F 'data=[
       {
  "event_name": "Purchase",
  "event_time": 1674000041,
  "user_data": {
    "em": [
      "309a0a5c3e211326ae75ca18196d301a9bdbd1a882a4d2569511033da23f0abd"
    ],
    "ph": [
      "254aa248acb47dd654ca3ea53f48c2c26d641d23d7e2e93a1ec56258df7674c4",
      "6f4fcb9deaeadc8f9746ae76d97ce1239e98b404efe5da3ee0b7149740f89ad6"
    ]
  },
  "custom_data": {
    "currency": "usd",
    "value": 123.45,
    "contents": [{
      "id": "product123",
      "quantity": 1
    }]
  },
  "action_source": "physical_store"
}
]' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v15.0/<DATASET_ID>/events

نوصي بالتحميل في الوقت الفعلي أو على أساس يومي للحصول على أفضل نتائج التحسين بحيث يمكن مطابقة البيانات بلا اتصال بشكل فعال مع أداء أي إعلانات تقوم بتشغيلها.

يمكن أن يصل event_time إلى 7 أيام قبل أن تتمكن من إرسال الحدث إلى Meta. إذا كان event_time في data أكبر من 7 أيام في الماضي، فإننا نُرجع رسالة خطأ على الطلب بأكمله ولا نعالج أي أحداث. بالنسبة إلى أحداث المتجر الفعلي وغير المتصل بـ physical_store كـ action_source، عليك تحميل المعاملات في غضون 62 يومًا من التحويل.

تتم معالجة البيانات التي تقوم بتحميلها في الوقت الفعلي حتى تتمكن دائمًا من عرض النتائج بمجرد إضافتها. يمكنك الرجوع إلى وثيقة مركز المساعدة حول أفضل الممارسات لبيانات أحداث التحويل بلا اتصال.

3. إعداد إلغاء التكرار

على عكس إلغاء التكرار الذي تم إعداده عبر واجهة API التحويلات وأحداث بيكسل Meta، يمكن إلغاء تكرار أحداث التحويل بلا اتصال مقابل أحداث التحويل بلا اتصال أخرى فقط. ندعم طريقتين لإلغاء التكرار: استنادًا إلى order_id أو استنادًا إلى user. يستخدم إلغاء التكرار مزيجًا من الحقول: dataset_id، event_time، event_name، item_number، والحقل الرئيسي بناءً على الطريقة في حمولة بيانات الحدث المحدد.

يستخدم إلغاء التكرار الافتراضي order_id مع مجموعة من الحقول أعلاه. إذا لم يكن order_id موجودًا في الحمولة، فسيتم استخدام منطق إلغاء التكرار القائم على user.

على سبيل المثال، عندما يكون هناك طلبين متطابقين event_time، event_name يحتويان على order_id نفسه أو مجموعة معلمات معلومات العملاء نفسها بدون orders_id، فسنعتبرهما أحداثًا مكررة ونأخذ الحدث الأول. يعمل أسلوب إلغاء التكرار المستند إلى user مع حقول معلمات معلومات العملاء نفسها فقط في حمولتي البيانات.

الحد الأقصى لفترة إلغاء التكرار هو 7 أيام.

4. استكشاف المشكلات وإصلاحها

يمكنك استخدام أداة مساعدة حمولة البيانات لإنشاء بيانات الحمولة:

اختر مصدر الإجراء physical_store عندما يكون ذلك ممكنًا. بمجرد استخدام واجهة API التحويلات، فإنك توافق على أن المعلمة action_source دقيقة حسب معلوماتك.
املأ معلومات الأحداث التي سيتم إرسالها إلى Meta
سيؤدي هذا إلى إنشاء حمولة بيانات الأحداث، والتي يمكن استخدامها كقالب لدمج واجهة API التحويلات

استخدم أداة اختبار الأحداث في مدير الأحداث للاختبار. يرجى ملاحظة أن أداة اختبار الأحداث تدعم أحداث الويب والتطبيقات فقط.

إرسال أحداث بلا اتصال باستخدام واجهة API التحويلات

المتطلبات الأساسية

مجموعة البيانات

الأذونات

التكوين

1. إعداد معلمات أحداث التحويل بلا اتصال

معلمات معلومات العملاء

معلمات البيانات المخصصة

2. إرسال الأحداث

3. إعداد إلغاء التكرار

4. استكشاف المشكلات وإصلاحها

راجع أيضًا

مقالات مركز مساعدة الأعمال