‏واجهة API التحويلات‏

استخدام API

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

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

واجهة API التحويلات: نظرة عامةالمعلمات

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

إرسال الطلبات

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

curl -X POST \
  -F 'data=[
       {
         "event_name": "Purchase",
         "event_time": 1715938590,
         "user_data": {
           "em": [
             "309a0a5c3e211326ae75ca18196d301a9bdbd1a882a4d2569511033da23f0abd"
           ],
           "ph": [
             "254aa248acb47dd654ca3ea53f48c2c26d641d23d7e2e93a1ec56258df7674c4",
             "6f4fcb9deaeadc8f9746ae76d97ce1239e98b404efe5da3ee0b7149740f89ad6"
           ],
           "client_ip_address": "123.123.123.123",
           "client_user_agent": "$CLIENT_USER_AGENT",
           "fbc": "fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890",
           "fbp": "fb.1.1558571054389.1098115397"
         },
         "custom_data": {
           "currency": "usd",
           "value": 123.45,
           "contents": [
             {
               "id": "product123",
               "quantity": 1,
               "delivery_category": "home_delivery"
             }
           ]
         },
         "event_source_url": "http://jaspers-market.com/product/123",
         "action_source": "website"
       }
     ]' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v19.0/<PIXEL_ID>/events
'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const Content = bizSdk.Content;
const CustomData = bizSdk.CustomData;
const DeliveryCategory = bizSdk.DeliveryCategory;
const EventRequest = bizSdk.EventRequest;
const UserData = bizSdk.UserData;
const ServerEvent = bizSdk.ServerEvent;

const access_token = '<ACCESS_TOKEN>';
const pixel_id = '<ADS_PIXEL_ID>';
const api = bizSdk.FacebookAdsApi.init(access_token);

let current_timestamp = Math.floor(new Date() / 1000);

const userData = (new UserData())
                .setEmails(['joe@eg.com'])
                .setPhones(['12345678901', '14251234567'])
                // It is recommended to send Client IP and User Agent for Conversions API Events.
                .setClientIpAddress(request.connection.remoteAddress)
                .setClientUserAgent(request.headers['user-agent'])
                .setFbp('fb.1.1558571054389.1098115397')
                .setFbc('fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890');

const content = (new Content())
                .setId('product123')
                .setQuantity(1)
                .setDeliveryCategory(DeliveryCategory.HOME_DELIVERY);

const customData = (new CustomData())
                .setContents([content])
                .setCurrency('usd')
                .setValue(123.45);

const serverEvent = (new ServerEvent())
                .setEventName('Purchase')
                .setEventTime(current_timestamp)
                .setUserData(userData)
                .setCustomData(customData)
                .setEventSourceUrl('http://jaspers-market.com/product/123')
                .setActionSource('website');

const eventsData = [serverEvent];
const eventRequest = (new EventRequest(access_token, pixel_id))
                .setEvents(eventsData);

eventRequest.execute().then(
  response => {
    console.log('Response: ', response);
  },
  err => {
    console.error('Error: ', err);
  }
);
require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;
use FacebookAds\Object\ServerSide\ActionSource;
use FacebookAds\Object\ServerSide\Content;
use FacebookAds\Object\ServerSide\CustomData;
use FacebookAds\Object\ServerSide\DeliveryCategory;
use FacebookAds\Object\ServerSide\Event;
use FacebookAds\Object\ServerSide\EventRequest;
use FacebookAds\Object\ServerSide\UserData;

$access_token = '<ACCESS_TOKEN>';
$pixel_id = '<ADS_PIXEL_ID>';

$api = Api::init(null, null, $access_token);
$api->setLogger(new CurlLogger());

$user_data = (new UserData())
    ->setEmails(array('joe@eg.com'))
    ->setPhones(array('12345678901', '14251234567'))
    // It is recommended to send Client IP and User Agent for Conversions API Events.
    ->setClientIpAddress($_SERVER['REMOTE_ADDR'])
    ->setClientUserAgent($_SERVER['HTTP_USER_AGENT'])
    ->setFbc('fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890')
    ->setFbp('fb.1.1558571054389.1098115397');

$content = (new Content())
    ->setProductId('product123')
    ->setQuantity(1)
    ->setDeliveryCategory(DeliveryCategory::HOME_DELIVERY);

$custom_data = (new CustomData())
    ->setContents(array($content))
    ->setCurrency('usd')
    ->setValue(123.45);

$event = (new Event())
    ->setEventName('Purchase')
    ->setEventTime(time())
    ->setEventSourceUrl('http://jaspers-market.com/product/123')
    ->setUserData($user_data)
    ->setCustomData($custom_data)
    ->setActionSource(ActionSource::WEBSITE);

$events = array();
array_push($events, $event);

$request = (new EventRequest($pixel_id))
    ->setEvents($events);
$response = $request->execute();
print_r($response);
import time

from facebook_business.adobjects.serverside.action_source import ActionSource
from facebook_business.adobjects.serverside.content import Content
from facebook_business.adobjects.serverside.custom_data import CustomData
from facebook_business.adobjects.serverside.delivery_category import DeliveryCategory
from facebook_business.adobjects.serverside.event import Event
from facebook_business.adobjects.serverside.event_request import EventRequest
from facebook_business.adobjects.serverside.user_data import UserData
from facebook_business.api import FacebookAdsApi

access_token = '<ACCESS_TOKEN>'
pixel_id = 'ADS_PIXEL_ID>'

FacebookAdsApi.init(access_token=access_token)

user_data = UserData(
    emails=['joe@eg.com'],
    phones=['12345678901', '14251234567'],
    # It is recommended to send Client IP and User Agent for Conversions API Events.
    client_ip_address=request.META.get('REMOTE_ADDR'),
    client_user_agent=request.headers['User-Agent'],
    fbc='fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890',
    fbp='fb.1.1558571054389.1098115397',
)

content = Content(
    product_id='product123',
    quantity=1,
    delivery_category=DeliveryCategory.HOME_DELIVERY,
)

custom_data = CustomData(
    contents=[content],
    currency='usd',
    value=123.45,
)

event = Event(
    event_name='Purchase',
    event_time=int(time.time()),
    user_data=user_data,
    custom_data=custom_data,
    event_source_url='http://jaspers-market.com/product/123',
    action_source=ActionSource.WEBSITE,
)

events = [event]

event_request = EventRequest(
    events=events,
    pixel_id=pixel_id,
)

event_response = event_request.execute()
print(event_response)
import com.facebook.ads.sdk.APIContext;
import com.facebook.ads.sdk.APIException;
import com.facebook.ads.sdk.serverside.ActionSource;
import com.facebook.ads.sdk.serverside.Content;
import com.facebook.ads.sdk.serverside.CustomData;
import com.facebook.ads.sdk.serverside.DeliveryCategory;
import com.facebook.ads.sdk.serverside.Event;
import com.facebook.ads.sdk.serverside.EventRequest;
import com.facebook.ads.sdk.serverside.EventResponse;
import com.facebook.ads.sdk.serverside.UserData;

import java.util.Arrays;

public class ServerSideApiExample {

  public static final String ACCESS_TOKEN = "<ACCESS_TOKEN>";
  public static final String PIXEL_ID = "<ADS_PIXEL_ID>";

  public static void main(String[] args) {
    APIContext context = new APIContext(ACCESS_TOKEN).enableDebug(true);
    context.setLogger(System.out);

    UserData userData = new UserData()
        .emails(Arrays.asList("joe@eg.com"))
        .phones(Arrays.asList("12345678901", "14251234567"))
        // It is recommended to send Client IP and User Agent for Conversions API Events.
        .clientIpAddress(clientIpAddress)
        .clientUserAgent(clientUserAgent)
        .fbc("fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890")
        .fbp("fb.1.1558571054389.1098115397");

    Content content = new Content()
        .productId("product123")
        .quantity(1L)
        .deliveryCategory(DeliveryCategory.home_delivery);

    CustomData customData = new CustomData()
        .addContent(content)
        .currency("usd")
        .value(123.45F);

    Event purchaseEvent = new Event();
    purchaseEvent.eventName("Purchase")
        .eventTime(System.currentTimeMillis() / 1000L)
        .userData(userData)
        .customData(customData)
        .eventSourceUrl("http://jaspers-market.com/product/123")
        .actionSource(ActionSource.website);

    EventRequest eventRequest = new EventRequest(PIXEL_ID, context);
    eventRequest.addDataItem(purchaseEvent);

    try {
      EventResponse response = eventRequest.execute();
      System.out.println(String.format("Standard API response : %s ", response));
    } catch (APIException e) {
      e.printStackTrace();
    }
  }
}
require 'facebook_ads'

access_token = '<ACCESS_TOKEN>'
pixel_id = '<ADS_PIXEL_ID>'

FacebookAds.configure do |config|
  config.access_token = access_token
end

user_data = FacebookAds::ServerSide::UserData.new(
    emails: ['joe@eg.com'],
    phones: ['12345678901', '14251234567'],
    # It is recommended to send Client IP and User Agent for Conversions API Events.
    client_ip_address: request.remote_ip,
    client_user_agent: request.user_agent,
    fbc: 'fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890',
    fbp: 'fb.1.1558571054389.1098115397'
)

content = FacebookAds::ServerSide::Content.new(
    product_id: 'product123',
    quantity: 1,
    delivery_category: 'home_delivery'
)

custom_data = FacebookAds::ServerSide::CustomData.new(
    contents: [content],
    currency: 'usd',
    value: 123.45
)

event = FacebookAds::ServerSide::Event.new(
    event_name: 'Purchase',
    event_time: Time.now.to_i,
    user_data: user_data,
    custom_data: custom_data,
    event_source_url: 'http://jaspers-market.com/product/123',
    action_source: 'website'
)

request = FacebookAds::ServerSide::EventRequest.new(
    pixel_id: pixel_id,
    events: [event]
)

print request.execute

أرفق رمز الوصول الآمن الذي تم إنشاؤه بالطلب باستخدام معلمة الاستعلام access_token. يمكنك أيضًا استخدام مستكشف Graph API لإجراء طلب POST لنقطة النهاية /<pixel_id>/events.

فيما يلي مثال على شكل النص الأساسي للطلب:

{
   "data": [
      {
         "event_name": "Purchase",
         "event_time": 1633552688,
         "event_id": "event.id.123",
         "event_source_url": "http:\/\/jaspers-market.com\/product\/123",         
         "action_source": "website",
         "user_data": {
            "client_ip_address": "192.19.9.9",
            "client_user_agent": "test ua",
            "em": [
               "309a0a5c3e211326ae75ca18196d301a9bdbd1a882a4d2569511033da23f0abd"
            ],
            "ph": [
               "254aa248acb47dd654ca3ea53f48c2c26d641d23d7e2e93a1ec56258df7674c4",
               "6f4fcb9deaeadc8f9746ae76d97ce1239e98b404efe5da3ee0b7149740f89ad6"
            ],
            "fbc": "fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890",
            "fbp": "fb.1.1558571054389.1098115397"
         },
         "custom_data": {
            "value": 100.2,
            "currency": "USD",
            "content_ids": [
               "product.id.123"
            ],
            "content_type": "product"
         },
         "opt_out": false
      },
      {
         "event_name": "Purchase",
         "event_time": 1633552688,
         "user_data": {
            "client_ip_address": "192.88.9.9",
            "client_user_agent": "test ua2"
         },
         "custom_data": {
            "value": 50.5,
            "currency": "USD"
         },
         "opt_out": false
      }
   ]
}

وقت التحميل مقابل وقت تحويل الحدث

event_time هو وقت معاملة الحدث. وينبغي إرسال الوقت في صورة طابع زمني بتنسيق Unix بالثواني للإشارة إلى الوقت الفعلي الذي وقع فيه الحدث. قد يكون الوقت المحدد مبكرًا عن الوقت الذي ترسل فيه الحدث إلى فيسبوك. ذلك من أجل تمكين المعالجة المجمّعة وتحسين أداء الخادم.

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

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

الطلبات المُجمعة

يمكنك إرسال 1,000 حدث كحد أقصى في data. ولكن للحصول على أفضل أداء، نوصيك بإرسال الأحداث في أقرب وقت فور وقوعها ومن الأفضل أن يكون في غضون ساعة من وقوع الحدث. وإذا كان أي حدث ترسله في الطلب المجمّع غير صالح، فسيتم رفض الطلب المجمّع بالكامل.

التجزئة

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

ميزات مجموعة SDK للنشاط التجاري لواجهة API التحويلات

تعرف على المزيد حول ثلاث ميزات معينة لمجموعة SDK للنشاط التجاري ومُصممة خصيصًا لمستخدمي واجهة API التحويلات: الطلبات غير المتزامنة والتجميع المتزامن وواجهة خدمات HTTP. الحد الأدنى لإصدار اللغة المطلوب لاستخدام هذه الميزات هو ما يلي:

  • PHP >= 7.2
  • Node.js >= 7.6.0
  • Java >= 8
  • Python >= 2.7
  • Ruby >= 2

تم إيقاف دعم مجموعة SDK النشاط التجاري للغة PHP بالإصدار 5 منذ يناير 2019. لذا يُرجى الترقية إلى لغة PHP بالإصدار 7 لاستخدام مجموعة SDK للنشاط التجاري.

إذا كان يتعين عليك استخدام لغة PHP بالإصدار 5، فيمكنك استخدام تنفيذ Swagger الذي نوفره.

معلمات واجهة API التحويلات

التحقق من صحة الأحداث

بعد إرسال الأحداث، تأكد من أننا تلقينا هذه الأحدث في مدير الأحداث:

  • في صفحة مصادر البيانات، انقر على البيكسل الذي يطابق PIXEL_ID في طلب POST لديك. ولمزيد من المعلومات، يمكنك الرجوع إلى مركز مساعدة الأعمال: التنقل في مدير الأحداث.
  • ثم انقر على نظرة عامة. وسيظهر عدد الأحداث الأولية والمتطابقة والمسندة التي تلقيناها. ضمن طريقة الاتصال، ستظهر لك القناة التي تم إرسال هذا الحدث من خلالها.
  • يمكنك النقر على كل حدث للحصول على معلومات أكثر تحديدًا.
  • بعد أن تبدأ في إرسال الأحداث، من المفترض أن تتمكن من التحقق منها في غضون 20 دقيقة. ويمكنك الآن البدء في إرسال الأحداث من الخادم لديك.

أداة اختبار الأحداث

يمكنك التحقق من تلقي أحداث الخادم بطريقة صحيحة من جانب فيسبوك وذلك باستخدام ميزة اختبار الأحداث المتوفرة في مدير الأحداث. وللعثور على الأداة، انتقل إلى Events Manager > Data Sources > Your Pixel > Test Events.

تعمل أداة اختبار الأحداث على إنشاء معرف اختبار. لذا أرسل معرف الاختبار في صورة معلمة test_event_code لبدء عرض نشاط الحدث في النافذة "اختبار الأحداث".

ملاحظة: يجب ألا يتم استخدام الحقل test_event_code إلا لأغراض الاختبار. ويجب إزالته عند إرسال حمولة بيانات الإنتاج.

لا يتم إلغاء الأحداث المُرسلة مع test_event_code. حيث تتدفق إلى مدير الأحداث وتُستخدم لأغراض الاستهداف وقياس الإعلانات.

فيما يلي مثال يوضح الطريقة التي ينبغي هيكلة الطلب بها:

{
   "data": [
      {
         "event_name": "ViewContent",
         "event_time": 1715937990,
         "event_id": "event.id.123",
         "event_source_url": "http:\/\/jaspers-market.com",
         "user_data": {
            "client_ip_address": "1.2.3.4",
            "client_user_agent": "test user agent"
         }
      }
   ],
   "test_event_code": "TEST123"
}

فيما يلي مثال على كيفية ظهور الطلب في مستكشف Graph API:

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

تظهر أحداث الخادم في النافذة "اختبار الأحداث" بمجرد إرسال الطلب.

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

بالنسبة لواجهتي API هاتين، يمكن تنفيذ خيارات معالجة البيانات من خلال إضافة data_processing_options وdata_processing_options_country وdata_processing_options_state داخل كل حدث ضمن معلمة البيانات للأحداث.

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

لعدم تمكين الاستخدام المحدود للبيانات (LDU) بشكل صريح، حدد مصفوفة فارغة لكل حدث أو ببساطة قم بإزالة الحقل في حمولة البيانات:

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

لتمكين الاستخدام المحدود للبيانات (LDU) وجعل Meta تحدد الموقع الجغرافي:

{
    "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
        }
    ]
}

لتمكين الاستخدام المحدود للبيانات (LDU) وتحديد الموقع يدويًا، على سبيل المثال لكاليفورنيا:

{
    "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
        }
    ]
}

تحميل واجهة المستخدم يدويًا

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


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

تقييدات واجهة API

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

لا يوجد تقييد محدد على معدلات استدعاء واجهة API التحويلات. ويتم احتساب استدعاءات واجهة API التحويلات كاستدعاءات API التسويق. علمًا بأن التقييد الوحيد هو أنه يمكنك إرسال 1,000 حدث كحد أقصى في وقت واحد. ولمزيد من المعلومات، يمكنك الرجوع إلى إرسال الطلبات.

تقييد معدلات الاستدعاء في واجهة API التسويق

استخدام API مجموعة SDK للأعمال في بوابة واجهة API التحويلات

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

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

المتطلبات

قبل استخدام أي من الميزات المدرجة أدناه، تحتاج إلى تثبيت مجموعة SDK من Meta للأعمال. راجع بدء استخدام مجموعة SDK من Meta للأعمال أو اتبع إرشادات README المدرجة هنا:

لا تتوفر هذه الميزات إلا على مجموعة SDK للأعمال في PHP وJava حاليًا. سيتم تنفيذ اللغات الأخرى بحلول نهاية عام 2023.

الحد الأدنى لإصدار اللغة المطلوب لاستخدام هذه الميزات هو:

PHP >= 7.2

Java >= 8

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

تنسيق معلمات CAPIGatewayIngressRequest

المعلمةالوصف
endpointUrl
string (سلسلة)

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


مثال: https://test.example.com


accessKey
string (سلسلة)

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

أدوات تعيين CAPIGatewayIngressRequest

المعلمةالوصف
setSendToDestinationOnly
Boolean (قيمة منطقية)

تمييز بقيمة منطقية يوضح ما إذا كان سيتم إرسال الأحداث إلى نقطة النهاية المحددة فقط.


علمًا بأن القيمة الافتراضية هي: False


setFilter
CustomEndpointRequest.Filter() function

وظيفة الفلترة التي تعمل على معالجة كل حدث. إذا أرجع منطق الفلترة القيمة true، فسيتم إرسال الحدث. بخلاف ذلك، سيتم تجاهل الحدث. يجب تنفيذ الوظيفة shouldSendEvent في الواجهة التي تحتوي على حدث المعلمة.


علمًا بأن القيمة الافتراضية هي: Null



مثال على الترحيل: PHP

بالنسبة إلى الأنظمة التي تستخدم بالفعل مجموعة SDK للأعمال، ما عليك سوى الإشارة إلى CAPIGatewayIngressRequest الجديد وإرفاقه بكائن customEndpoint لدى eventRequest.

// this is the standard event request that we attach events to
$event_request = new EventRequest($this->pixel_id);
$capiIngressRequest = new CAPIGatewayIngressRequest($this->cb_url, $this->access_key);
$event_request->setCustomEndpoint($capiIngressRequest);
// pass the events to this event Request object
$event_request->setEvents($events);
$event_request->execute()

مثال على الترحيل: Java

بالنسبة إلى الأنظمة التي تستخدم بالفعل مجموعة SDK للأعمال، ما عليك سوى الإشارة إلى CAPIGatewayIngressRequest الجديد وإرفاقه بكائن customEndpoint لدى eventRequest.

// this is the standard event request that we attach events to


EventRequest eventRequest = new EventRequest(PIXEL_ID, context);


CAPIGatewayIngressRequest capiSyncRequest = new CAPIGatewayIngressRequest(CB_URL, CAPIG_ACCESS_KEY);
eventRequest.setCustomEndpoint(capiSyncRequest);
eventRequest.addDataItem(testEvent);
eventRequest.execute();

خيار المزامنة

مثال على رمز PHP

$api = Api::init(null, null, $this->access_token);
$api->setLogger(new CurlLogger());
$event_request = new EventRequest($this->pixel_id);
$capiIngressRequest = new CAPIGatewayIngressRequest($this->cb_url, $this->access_key);
$event_request->setCustomEndpoint($capiIngressRequest);
$user_data = (new UserData())
   ->setEmails(array('joe@eg.com'))
   ->setPhones(array('12345678901', '14251234567'))
   ->setFbc('fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890')
   ->setFbp('fb.1.1558571054389.1098115397');
$event1 = (new Event())
   ->setEventName('Purchase')
   ->setEventId('125')
   ->setEventTime(time())
   ->setEventSourceUrl('http://jaspers-market.com/product/123')
   ->setUserData($user_data);
$events = array($event1, $event2);
$event_request->setEvents($events);
$response = $event_request->execute();
print($response->__toString());

مثال على رمز Java

EventRequest eventRequest = new EventRequest(PIXEL_ID, context);
UserData userData = new UserData()
       .email("abc@eg.com");
CAPIGatewayIngressRequest capiSyncRequest = new CAPIGatewayIngressRequest(CB_URL, CAPIG_ACCESS_KEY);
eventRequest.setCustomEndpoint(capiSyncRequest);
Event testEvent = new Event();
testEvent.eventId("125").eventName("Purchase")
       .eventTime(System.currentTimeMillis() / 1000L)
       .userData(userData)
       .dataProcessingOptions(new String[]{}).setEventId("134423232");
eventRequest.namespaceId("11")
       .uploadId("22222")
       .uploadTag("upload-tag-4")
       .uploadSource("upload-source-4")
       .testEventCode("test-event-code-5")
       .partnerAgent("partner-agent-6");
eventRequest.addDataItem(testEvent);
eventRequest.execute();

خيار عدم المزامنة

مثال على رمز PHP

$api = Api::init(null, null, $this->access_token);
$api->setLogger(new CurlLogger());
$event_request = new EventRequestAsync($this->pixel_id);
$capiIngressRequest = new CAPIGatewayIngressRequest($this->cb_url, $this->access_key);
$capiIngressRequest->setSendToDestinationOnly(true);
$event_request->setCustomEndpoint($capiIngressRequest);
$event1 = (new Event())
   ->setEventName('test Async Event')
   ->setEventId('134423232')
   ->setEventTime(time())
   ->setEventSourceUrl('http://jaspers-market.com/product/123');
$events = array($event1, $event2);
$event_request->setEvents($events);
$response = $event_request->execute()->wait();

مثال على رمز Java

EventRequest eventRequest = new EventRequest(PIXEL_ID, context);
UserData userData = new UserData()
       .email("abc@eg.com");
CAPIGatewayIngressRequest capiSyncRequest = new CAPIGatewayIngressRequest(CB_URL, CAPIG_ACCESS_KEY);
capiSyncRequest.setSendToDestinationOnly(true);
eventRequest.setCustomEndpoint(capiSyncRequest);
Event testEvent = new Event();
testEvent.eventName("test Async Event")
       .eventTime(System.currentTimeMillis() / 1000L)
       .userData(userData)
       .dataProcessingOptions(new String[]{}).setEventId("134423232");
eventRequest.namespaceId("11222")
       .uploadId("22222")
       .uploadTag("upload-tag-4")
       .uploadSource("upload-source-4")
       .testEventCode("test-event-code-5")
       .partnerAgent("partner-agent-6");
eventRequest.addDataItem(testEvent);
eventRequest.executeAsync();

وظيفة الفلترة

مثال على رمز PHP

lass APIFilter implements Filter {
   public function shouldSendEvent(Event $event): bool
   {
       if ($event->getEventId() === '125') {
           return false;
       }
       return true;
   }
}
$capiIngressRequest = new CAPIGatewayIngressRequest($this->cb_url, $this->access_key);
$event_request->setCustomEndpoint($capiIngressRequest);
$capiIngressRequest->setFilter(new APIFilter());

مثال على رمز Java

CAPIGatewayIngressRequest capiSyncRequest = new CAPIGatewayIngressRequest(CB_URL, CAPIG_ACCESS_KEY);
eventRequest.setCustomEndpoint(capiSyncRequest);


capiSyncRequest.setFilter(new CustomEndpointRequest.Filter() {
   @Override
   public boolean shouldSendEvent(Event event) {
   if (event.getEventId().equals("125")) {
       return true;
   }
   return false;
}
});

معرفة المزيد