API التحويلات بلا اتصال

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

قبل البدء

لاستخدام API هذه، تحتاج إلى ما يلي:

1. مدير الأعمال من Meta

إذا لم يكن لديك حساب، فأنشئ واحدًا.

2. معرف تطبيق Meta

للوصول إلى API التسويق. لإنشاء تطبيق Meta:

• تفضل بزيارة مدير الأعمال > إعدادات مدير الأعمال.
• حدد التطبيقات.
• انقر على إضافة تطبيق جديد واتبع التعليمات.

3. مراجعة التطبيقات والأذونات

تعتمد القواعد المتعلقة بمراجعة التطبيقات والأذونات على طريقة تنفيذ واجهة API لدينا:

4. الرمز والمستخدم في نظام مدير الأعمال

عند وصول مستخدم النظام، يمكن لتطبيقك إرسال بيانات إلى Meta عبر API. لإنشاء ذلك:

• تفضل بزيارة مدير الأعمال > إعدادات مدير الأعمال.
• حدد مستخدمو النظام.
• انقر على إضافة مستخدم نظام جديد.
• حدّد مستخدم النظام المسؤول كدور لمستخدم النظام.

يوفر رمز الوصول إمكانية الوصول إلى بيانات Meta. لإنشاء رموز وصول مستخدم النظام:

• تفضل بزيارة مدير الأعمال > إعدادات مدير الأعمال.
• حدد مستخدمو النظام.
• حدد مستخدم النظام وانقر على إنشاء رمز جديد.
• حدد تطبيقك > بالنسبة للنطاق، حدد ads_management.

5. الحساب الإعلاني

تحتاج إلى حساب إعلاني لتشغيل الحملات الإعلانية على Meta. لإنشاء حساب إعلاني، يمكنك الرجوع إلى API التسويق أو مركز مساعدة الأعمال: حول إعدادات الأعمال في مدير الأعمال من Meta.

6. منح مستخدم النظام إمكانية الوصول إلى الحساب الإعلاني

امنح مستخدم النظام إمكانية الوصول إلى حسابك الإعلاني.

• انتقل إلى مدير الأعمال > إعدادات النشاط التجاري.
• حدد مستخدمو النظام.
• حدد مستخدم النظام وانقر على تعيين الأصول.
• حدد حسابك الإعلاني.

7. مجموعة أحداث التحويل بلا اتصال

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

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

تحميل بيانات الأحداث

تحتاج إلى وصول محدد لإنشاء مجموعات أحداث التحويل بلا اتصال أو تحميل البيانات لمجموعة أحداث أو عرضها. وتحتاج أيضًا إلى هذا الوصول لتعيين هذه الأذونات إلى حساب إعلاني. ويجب أن تتمتع بأحد الأدوار التالية:

• مسؤول مدير الأعمال
• مستخدم النظام المسؤول الذي أنشأ مجموعة أحداث التحويل بلا اتصال
• مسؤول في حساب ad_account المتصل بمجموعة أحداث التحويل بلا اتصال

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

1. إنشاء مجموعة أحداث التحويل بلا اتصال

curl 
  -F 'access_token=<SYSTEM_USER_ACCESS_TOKEN>' 
  -F 'name=offline_event_set',
  -F 'description=conversion data used for superbowl campaign',
  https://graph.facebook.com/<API_VERSION>/<BUSINESS_MANAGER_ID>/offline_conversion_data_sets

قم بإجراء طلب HTTP POST:

POST /<BUSINESS_MANAGER_ID>/offline_conversion_data_sets HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<BUSINESS_MANAGER_ID>/offline_conversion_data_sets

تتضمن الاستجابة معرف id لمجموعة الأحداث:

{
  "id": <OFFLINE_EVENT_SET_ID>
}

المعلمات

2. تعيين أذونات الحساب الإعلاني

لتعيين أذونات التتبع والقراءة إلى حساب إعلاني:

POST /<OFFLINE_EVENT_SET_ID>/adaccounts HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/adaccounts

المعلمات

3. تعيين تتبع الإعلان

عند تحديث tracking_spec، فإننا نستبدله. تأكد من إجراء طلب GET أولًا، ثم قم بإلحاق سلسلة String المرتبطة في مجموعة أحداث التحويل بلا اتصال بالمعلمة tracking_spec الحالية. ويمكنك الرجوع إلى إدارة الإعلانات أو استخدام مدير الإعلانات. فعلى سبيل المثال، أدخل مواصفات مناسبة بشأن التتبع:

curl \
  -F 'tracking_spec=[{action.type:"offline_conversion", dataset:["123"]}]' \
  -F 'access_token=<SYSTEM_USER_ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/<AD_ID>

لتحديث المواصفات الخاصة بتتبع إعلاناتك:

POST /<AD_ID>/?tracking_specs=[{"action.type":"offline_conversion","dataset": <OFFLINE_EVENT_SET_ID>}] HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<AD_ID>/?tracking_specs=[{"action.type":"offline_conversion","dataset": <OFFLINE_EVENT_SET_ID>}]

المعلمات

4. تحميل أحداث التحويل بلا اتصال

يجب تحميل المعاملة في غضون 62 يومًا من حدوث التحويل. وقم بتحميل بيانات التحويل:

curl \
  -F 'access_token=SYSTEM_USER_ACCESS_TOKEN' \
  -F 'upload_tag=store_data' \
  -F 'data=[ \
    { 
      match_keys: {"phone": ["HASH1","HASH2"], "email": ["HASH3","HASH4"]}, 
      currency: "USD", 
      value: 16,
      event_name: "Purchase",
      event_time: 1456870902,
      contents: [
        {id: "A", quantity: 1},
        {id: "B", quantity: 2},
        {id: "C", quantity: 1}
      ]
      custom_data: {             
      },
    }, 
    { 
      match_keys: {"lead_id": "12345"}, 
      event_name: "Lead",
      event_time: 1446336000,
      contents: [
        {id: "A", quantity: 1},
        {id: "B", quantity: 2},
        {id: "C", quantity: 1}
      ]
      custom_data: {
        event_source: "email",
        action_type: "sent_open_click",
        email_type: "email_type_code", 
        email_provider: "gmail_yahoo_hotmail",
      }
    }, 
  ]'
  https://graph.facebook.com/VERSION/OFFLINE_EVENT_SET_ID/events

لإرسال التحويلات، قم بإجراء طلب HTTP POST:

POST /<OFFLINE_EVENT_SET_ID>/events HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/events

المعلمات

استخدم الإشارة upload_tag نفسها لكل استدعاءات واجهة API تحميل الأحداث الموجودة في الدُفعة نفسها لتجميعها. ويساعدك ذلك في تصحيح أخطاء عمليات تحميل أحداث التحويل، ويجب عليك استخدام ذلك في عمليات تحميل أحداث تحويل يتم إجراؤها في أكثر من استدعاء واجهة API واحد.

تتضمن المعلمات في data ما يلي:

فعلى سبيل المثال، يمكنك تحميل المعلومات باستخدام الحقل data:

{
  match_keys: MATCH_KEYS,
  event_time: EVENT_TIME,
  event_name: "Purchase",
  value: 400,
  currency: "USD",
  contents: [
    {
        id: "A",
        quantity: 1,
        brand: "brand_of_A",
        category: "Apparel & Accessories | Clothing",
        price: 100,
    },
    {
        id: "B",
        quantity: 2,
        brand: "brand_of_B",
        category: "Apparel & Accessories | Shoes",
        price: 50,
    },
    {
        id: "C",
        quantity: 1,
        brand: "brand_of_C",
        category: "Apparel & Accessories | Jewelry | Watches",
        price: 200,
    }
  ],
}

استخدم الإشارة upload_tag نفسها لكل استدعاءات واجهة API تحميل الأحداث الموجودة في الدُفعة نفسها لتجميعها. ويساعدك ذلك في تصحيح أخطاء عمليات تحميل أحداث التحويل، ويجب عليك استخدام ذلك في عمليات تحميل أحداث تحويل يتم إجراؤها في أكثر من استدعاء واجهة API واحد.

مفاتيح المطابقة

match_keys هي مجموعة من المعرفات اللازمة لمطابقة الأشخاص من أجل الإسناد. ويمكنك الرجوع إلى الجماهير المخصصة من بيانات إدارة علاقات العملاء لتجزئة بياناتك وفهمها. يتم دعم SHA256 فقط ولا نقبل أي بيانات غير مُجزأة.

الاستجابة:

في رسائل الخطأ، يظهر لك استثناء يتضمن الإدخالات غير الصالحة وسبب هذا الخطأ. ويمكنك إصلاح الأخطاء أو تخطي صفوف البيانات التي تحتوي على أخطاء وإعادة محاولة استدعاء واجهة API.

عرض إحصائيات التحميل

يمكن للمسؤول في مدير الأعمال أو مستخدم النظام الذي قام بإنشاء مجموعة أحداث التحويل بلا اتصال استرداد إحصائيات التحميل. كما يمكن لأي مسؤول في حساب ad_account المرتبط بمجموعة أحداث التحويل بلا اتصال قراءة هذه البيانات.

لعرض إحصائيات عن مجموعات أحداث التحويل بلا اتصال مثل الإدخالات الصالحة والإدخالات المطابقة:

GET /<OFFLINE_EVENT_SET_ID>/uploads HTTP/1.1
Host: graph.facebook.com

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/uploads

يمكنك عرض تقسيمات يومية لأحداث التحويل بلا اتصال في Offline Events Manager في مدير الأعمال. للحصول على تقسيمات أكثر دقة، قم بإجراء هذا الاستدعاء:

GET /<OFFLINE_EVENT_SET_ID>/stats HTTP/1.1
Host: graph.facebook.com

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/stats

المعلمات

إنشاء تحويلات مخصصة بلا اتصال

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

لإنشاء تحويل مخصص باستخدام أحداث التحويل بلا اتصال، قم بإجراء طلب POST:

POST /act_<ACCOUNT_ID>/customconversions HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/act_<ACCOUNT_ID>/customconversions

المعلمات:

مثال الاستجابة في حالة النجاح:

{
  "id": <CUSTOM_CONVERSION_ID>
}

القياس باستخدام البيانات المخصصة

يمكنك استخدام الحقل custom_data لإنشاء قواعد تحدد فيما بعد ما إذا كان التحويل مهمًا أم لا. ويتشابه ذلك مع الجماهير المخصصة بلا اتصال. ويبلغ الحد الأقصى لعدد التحويلات المخصصة التي يمكنك الحصول عليها لكل حساب إعلاني 40 تحويلًا.

فعلى سبيل المثال، يمكنك تضمين فئة المنتج في عمليات التحميل باستخدام custom_data:

data=[
  {
    match_keys: {"phone": ["<HASH>","<HASH>"], "email": ["<HASH>","<HASH>"]}, 
    currency: "USD", 
    value: 16,
    event_name: "Purchase",
    event_time: 1456870902,
    custom_data: {
      product_category: "ICECREAM",
    },
  },
]

بعد ذلك، يمكنك استخدام custom_data.{YOUR_CUSTOM_PARAM} لإنشاء قاعدة تحويل مخصص:

curl \
  -F 'name=Ice Cream Purchasers' \
  -F 'custom_event_type=Purchase' \
  -F 'event_source_id=<OFFLINE_EVENT_SET_ID>' \
  -F 'rule={"and": [{"event_name":{"eq":"Purchase"}},{"custom_data.product_category":{"i_contains":"ICECREAM"}}]}' \
  -F 'access_token=<ACCESS_TOKEN>' \

"https://graph.facebook.com/<API_VERSION>/act_<ACCOUNT_ID>/customconversions"

التحويلات بلا اتصال للشركاء

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

1. الشريك - إنشاء مجموعة أحداث تحويل بلا اتصال
2. الشريك - مشاركة مجموعة أحداث التحويل مع حساب مدير الأعمال الخاص بالعميل
3. العميل - تعيين إذن التتبع بلا اتصال للحساب الإعلاني
4. العميل - تعيين التتبع بلا اتصال على الإعلانات
5. الشريك - تحميل أحداث التحويل بلا اتصال، عرض الإحصائيات
6. الشريك - عرض رؤى الإعلانات للعميل

تختلف هذه الخطوات تبعًا لكيفية إعداد أذونات الشريك أو الوكالة مع الحسابات الإعلانية للعميل:

• يمكنك امتلاك كل الحسابات الإعلانية أو مجموعات أحداث التحويل أو أي أصول أخرى خاصة بالعميل.
• يمكنك الحصول على إذن للوصول إلى أصول العميل من أجل اتخاذ إجراءات محددة.

لإعداد هذه الأذونات، يمكنك الرجوع إلى أصول مدير الأعمال.

الشريك - مشاركة مجموعة أحداث التحويل

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

GET /<OFFLINE_EVENT_SET_ID>/agencies HTTP/1.1
Host: graph.facebook.com

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/agencies

المعلمات

العميل - تعيين إذن التتبع بلا اتصال للحساب الإعلاني

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

يمكنك تعيين أذونات عرض وتتبع حدث التحويل بلا اتصال إلى حساب إعلاني باستخدام هذا الاستدعاء:

POST /<OFFLINE_EVENT_SET_ID>/adaccounts HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/adaccounts

المعلمات

توفير المعرفات الخارجية

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

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

توفير match_keys فقط

نستخدم match_keys لمحاولة تحديد ما إذا كان يمكن مطابقة بيانات التحويل التي شاركتها مع مستخدم Meta. إذا حاولت توفير match_keys، فلا يمكنك توفير معلمة namespace_id أيضًا.

توفير match_keys وextern_id

نستخدم match_keys لمحاولة العثور على الأشخاص على Meta وإعادة توجيه التعيينات من {dataset_id, extern_id} إلى {facebook_user_id}. إذا حاولت توفير match_keys وextern_id، فلا يمكنك تقديم معلمة namespace_id أيضًا.

توفير extern_id فقط

إذا كنت قد أرسلت بالفعل بيانات تتضمن match_keys وextern_id، فسيستخدم Meta {dataset_id, extern_id} لاسترداد {facebook_user_id}.

توفير namespace_id

تنطبق المعلمة namespace_id على استدعاء واجهة API بالكامل. يمكنك استخدامها للإحالة إلى مجموعة أحداث تحويل بلا اتصال أخرى يملكها معرف الملف الشخصي للنشاط التجاري أو الشريك، أو يمكن الوصول إليها بواسطته. إذا كنت قد أرسلت بيانات مع match_keys وextern_id، فسيستخدم Meta {namespace_id, extern_id} لاسترداد {facebook_user_id}. يجب توفير extern_id واحد فقط لكل صف من البيانات.

الرؤى والإسناد

يمكنك عرض أحداث التحويل بلا اتصال التي تم إسنادها إلى إعلان قام شخص ما بعرضه أو النقر عليه. ونقوم بإسناد أحداث التحويل بلا اتصال بعد مرور أكثر من يوم واحد. ويعني ذلك أنه يجب عليك تعيين فترة الإسناد إلى 28d_view أو action_attribution_windows=['28d_view']'، وإلا فلن تظهر لك أي تحويلات في التقارير. كما يمكنك الرجوع إلى واجهة API الرؤى ودليل الرؤى.

GET /act_<ADACCOUNT_ID>/insights HTTP/1.1
Host: graph.facebook.com

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/act_<ADACCOUNT_ID>/insights

المعلمات

تبدو النتائج كما يلي:

{
  "data": [
    {
      "date_start": "2015-12-01",
      "date_stop": "2015-12-01",
      "actions": [
        {
          "action_type": "offline_conversion.purchase",
          "value": 1
        },
        {
          "action_type": "offsite_conversion.lead",
          "value": 3
        },
      ],
      ...
    }
  ]
}

فعلى سبيل المثال، لعرض الإسناد:

curl -G \
  -d 'access_token=<SYSTEM_USER_ACCESS_TOKEN>' \
  -d 'fields=unique_actions,action_values' \
  https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/insights

تبدو النتائج كما يلي:

{
  "data": [
    {
      "unique_actions": [
        {
          "action_type": "link_click",
          "value": 94
        },
        {
          "action_type": "offline_conversion",
          "value": 1
        },
        {
          "action_type": "offline_conversion.purchase",
          "value": 1
        },
        {
....
          "value": 1
        }
      ],
      "action_values": [
        {
          "action_type": "offline_conversion.purchase",
          "value": 27.5
        },
        {
          "action_type": "offline_conversion",
          "value": 27.5
        }
      ],
      "date_start": "2016-06-06",
      "date_stop": "2016-06-07"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MAZDZD"
    }
  }
}

خيارات معالجة البيانات لمستخدمي الولايات المتحدة

{
    "data": [
        {
            "event_name": "Purchase",
            "event_time": <EVENT_TIME>,
            "user_data": {
                "em": "<EMAIL>"
            },
            "custom_data": {
                "currency": "<CURRENCY>",
                "value": "<VALUE>"
            },
            "data_processing_options": []
        }
    ]
}

{
    "data": [
        {
            "event_name": "Purchase",
            "event_time": <EVENT_TIME>,
            "user_data": {
                "em": "<EMAIL>",
                "client_ip_address": "256.256.256.256"
            },
            "custom_data": {
                "currency": "<CURRENCY>",
                "value": "<VALUE>"
            },
            "data_processing_options": ["LDU"],
            "data_processing_options_country": 0,
            "data_processing_options_state": 0
        }
    ]
}

{
    "data": [
        {
            "event_name": "Purchase",
            "event_time": <EVENT_TIME>,
            "user_data": {
                "em": "<EMAIL>"
            },
            "custom_data": {
                "currency": "<CURRENCY>",
                "value": "<VALUE>"
            },
            "data_processing_options": ["LDU"],
            "data_processing_options_country": 1,
            "data_processing_options_state": 1000
        }
    ]
}

تعرف على المزيد حول خيارات معالجة البيانات.