การใช้ API

เมื่อคุณทำตามข้อกำหนดเบื้องต้นในหน้าเริ่มต้นใช้งานเรียบร้อยแล้ว ให้ดูหน้านี้เพื่อเรียนรู้วิธีส่งเหตุการณ์และวิธีใช้เครื่องมือทดสอบเหตุการณ์ เมื่อคุณส่งเหตุการณ์แล้ว ให้ตรวจสอบยืนยันการตั้งค่าของคุณ

API คอนเวอร์ชั่นจะอิงตาม API การตลาดของ Facebook ซึ่งสร้างขึ้นจาก API กราฟของเรา API การตลาดและ API กราฟมีกำหนดการเลิกใช้เวอร์ชั่นที่แตกต่างกัน รอบการเผยแพร่ของเราจะสอดคล้องกับ API กราฟ ดังนั้นจะมีการรองรับทุกเวอร์ชั่นเป็นเวลาอย่างน้อย 2 ปี ข้อยกเว้นนี้ใช้ได้กับ API คอนเวอร์ชั่นเท่านั้น

ส่งคำขอ

หากต้องการส่งเหตุการณ์ใหม่ ให้สร้างคำขอ POST ไปยังจุดเชื่อมโยง /events ของ API นี้จากเส้นทางนี้: https://graph.facebook.com/{API_VERSION}/{PIXEL_ID}/events?access_token={TOKEN} เมื่อคุณโพสต์ไปยังจุดเชื่อมโยงนี้ Facebook จะสร้างเหตุการณ์บนเซิร์ฟเวอร์ใหม่

curl -X POST \ -F 'data=[ { "event_name": "Purchase", "event_time": 1762902353, "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/v24.0/<PIXEL_ID>/events

แนบโทเค็นการเข้าถึงอย่างปลอดภัยที่สร้างขึ้นโดยใช้พารามิเตอร์การสืบค้น access_token ไปกับคำขอ นอกจากนี้คุณยังสามารถใช้ Graph API Explorer เพื่อ 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 ในหน่วยวินาทีที่ระบุเวลาที่เกิดเหตุการณ์จริง ทั้งนี้ เวลาที่ระบุอาจเร็วกว่าเวลาที่คุณส่งเหตุการณ์ไปยัง Facebook เพื่อให้สามารถปรับการประมวลผลแบบกลุ่มและประสิทธิภาพของเซิร์ฟเวอร์ให้เหมาะสม

event_time อาจเร็วกว่าถึง 7 วันก่อนที่คุณจะส่งเหตุการณ์ไปยัง Meta หาก event_time ใน data ผ่านมาแล้วมากกว่า 7 วัน เราจะส่งคืนข้อผิดพลาดสำหรับคำขอทั้งหมด และจะไม่ประมวลผลเหตุการณ์ สำหรับเหตุการณ์ออฟไลน์และเหตุการณ์หน้าร้านจริงที่มี physical_store เป็น action_source คุณควรอัพโหลดการดำเนินการภายใน 62 วันนับจากการสนทนา

คำขอแบบแบตช์

คุณสามารถส่งได้ถึง 1,000 เหตุการณ์ใน data อย่างไรก็ตาม เพื่อประสิทธิภาพสูงสุด เราขอแนะนำให้คุณส่งเหตุการณ์ทันทีที่เกิดเหตุการณ์ดังกล่าวขึ้น และควรดำเนินการภายใน 1 ชั่วโมงหลังเกิดเหตุการณ์ขึ้นจึงจะดีที่สุด หากเหตุการณ์ใดๆ ที่คุณส่งมาในแบตช์ไม่ถูกต้อง เราจะปฏิเสธทั้งแบตช์

การแฮช

โปรดดูที่หน้าพารามิเตอร์ข้อมูลลูกค้าเพื่อดูว่าพารามิเตอร์ใดที่ควรแฮชก่อนส่งไปยัง Facebook หากคุณใช้ Business SDK ของเรา SDK จะดำเนินการแฮชให้คุณ

ฟีเจอร์ของ Business SDK สำหรับ API คอนเวอร์ชั่น

เรียนรู้เพิ่มเติมเกี่ยวกับฟีเจอร์เฉพาะ 3 รายการของ Business SDK ที่ออกแบบมาเพื่อผู้ใช้ API คอนเวอร์ชั่นโดยเฉพาะ ได้แก่ คำขอแบบไม่ซิงโครไนซ์การจัดกลุ่มในเวลาเดียวกัน และอินเทอร์เฟซบริการ HTTP ในการใช้ฟีเจอร์เหล่านี้ คุณต้องมีเวอร์ชั่นภาษาขั้นต่ำดังต่อไปนี้

• PHP เวอร์ชั่น 7.2 ขึ้นไป
• Node.js เวอร์ชั่น 7.6.0 ขึ้นไป
• Java เวอร์ชั่น 8 ขึ้นไป
• Python เวอร์ชั่น 2.7 ขึ้นไป
• Ruby เวอร์ชั่น 2 ขึ้นไป

ตรวจสอบยืนยันเหตุการณ์

หลังจากที่ส่งเหตุการณ์ของคุณแล้ว ให้ยืนยันว่าเราได้รับเหตุการณ์ดังกล่าวในตัวจัดการเหตุการณ์ดังนี้

• บนหน้าแหล่งข้อมูล ให้คลิกพิกเซลที่ตรงกับ PIXEL_ID ในคำขอ POST ของคุณ คุณสามารถดูข้อมูลเพิ่มเติมได้ที่ศูนย์ช่วยเหลือทางธุรกิจ: ไปยังส่วนต่างๆ ในตัวจัดการเหตุการณ์
• จากนั้น คลิกที่ภาพรวม คุณจะเห็นจำนวนเหตุการณ์ที่เป็นข้อมูลดิบ เหตุการณ์ที่ตรงกัน และเหตุการณ์ที่มีการระบุที่มาที่เราได้รับ ในส่วนวิธีการเชื่อมต่อ คุณจะเห็นช่องทางที่ส่งเหตุการณ์มา

• คุณสามารถคลิกที่แต่ละเหตุการณ์เพื่อดูข้อมูลเฉพาะเจาะจงเพิ่มเติมได้

• คุณควรตรวจสอบยืนยันเหตุการณ์ได้ภายใน 20 นาทีหลังจากที่คุณเริ่มส่งเหตุการณ์ ตอนนี้คุณก็สามารถเริ่มส่งเหตุการณ์จากเซิร์ฟเวอร์ได้แล้ว

เครื่องมือทดสอบเหตุการณ์

คุณสามารถตรวจสอบยืนยันว่า Facebook ได้รับเหตุการณ์บนเซิร์ฟเวอร์ของคุณอย่างถูกต้องโดยใช้ฟีเจอร์ "ทดสอบเหตุการณ์" ในตัวจัดการเหตุการณ์ หากต้องการค้นหาเครื่องมือ ให้ไปที่ Events Manager > Data Sources > Your Pixel > Test Events

เครื่องมือทดสอบเหตุการณ์จะสร้าง ID ทดสอบ ส่ง ID ทดสอบเป็นพารามิเตอร์ test_event_code เพื่อเริ่มดูกิจกรรมของเหตุการณ์ปรากฏขึ้นในหน้าต่าง "ทดสอบเหตุการณ์"

ต่อไปนี้คือตัวอย่างวิธีจัดโครงสร้างคำขอ:

{
   "data": [
      {
         "event_name": "ViewContent",
         "event_time": 1763819226,
         "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 Explorer:

เหตุการณ์บนเซิร์ฟเวอร์ของคุณจะปรากฏขึ้นในหน้าต่าง "ทดสอบเหตุการณ์" เมื่อมีการส่งคำขอ

ตัวเลือกการประมวลผลข้อมูลสำหรับผู้ใช้ในสหรัฐฯ

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

โปรดเรียนรู้เพิ่มเติมเกี่ยวกับตัวเลือกการประมวลผลข้อมูล

ขีดจำกัดของ API

API การตลาดมีตรรกะการจำกัดอัตราของตัวเอง และไม่รวมอยู่ในการจำกัดอัตรา API กราฟใดๆ ดังนั้น หากคุณทำการเรียก API การตลาด ก็จะไม่ถูกนำไปคำนวณในการจำกัดผลลัพธ์ของ API กราฟ

API คอนเวอร์ชั่นไม่มีการจำกัดอัตราที่เฉพาะเจาะจง การเรียก API คอนเวอร์ชั่นจะนับเป็นการเรียก API การตลาด ข้อจำกัดเพียงอย่างเดียวคือ คุณสามารถส่งเหตุการณ์ถึงเราได้สูงสุดครั้งละ 1,000 เหตุการณ์ ดูข้อมูลเพิ่มเติมได้ที่หัวข้อส่งคำขอ

การใช้งาน API Business SDK ในเกตเวย์ API คอนเวอร์ชั่น

คู่มือนี้จะช่วยคุณในการใช้ฟีเจอร์ขั้นสูงต่างๆ ของ Meta Business SDK ที่ออกแบบมาสำหรับผู้ใช้เกตเวย์ API คอนเวอร์ชั่นโดยเฉพาะ โปรดดูการใช้งานเกตเวย์ API คอนเวอร์ชั่นขั้นพื้นฐานที่เอกสารประกอบเกี่ยวกับเกตเวย์ API คอนเวอร์ชั่น

ส่งเหตุการณ์ไปยังอินสแตนซ์เกตเวย์ API คอนเวอร์ชั่นของคุณ

ข้อกำหนด

คุณจำเป็นต้องติดตั้ง Meta Business SDK ไว้ก่อนจึงจะใช้ฟีเจอร์ทั้งหมดในรายการด้านล่างนี้ได้ โปรดดู "เริ่มต้นใช้งาน Meta Business SDK" หรือปฏิบัติตามคำแนะนำ README ที่ระบุไว้ที่นี่

• PHP: facebook-php-business-sdk
• Node.js: facebook-nodejs-business-sdk
• Java: facebook-java-business-sdk
• Python: facebook-python-business-sdk
• Ruby: facebook-ruby-business-sdk

เวอร์ชั่นภาษาขั้นต่ำที่ต้องมีในการใช้ฟีเจอร์เหล่านี้มีดังต่อไปนี้

PHP เวอร์ชั่น 7.2 ขึ้นไป

Java เวอร์ชั่น 8 ขึ้นไป

หมายเหตุ: หากต้องการลบเหตุการณ์ที่ซ้ำกันออกให้กับตำแหน่งข้อมูล API คอนเวอร์ชั่น โปรดส่ง eventId ในคำขอของคุณ ซึ่งจะช่วยป้องกันไม่ให้เหตุการณ์ที่ซ้ำกันแสดงขึ้นมาในกรณีที่เปิดใช้งานการเผยแพร่ API คอนเวอร์ชั่น

การจัดรูปแบบพารามิเตอร์ CAPIGatewayIngressRequest

ตัวตั้งค่า CAPIGatewayIngressRequest

ตัวอย่างการย้าย: PHP

สำหรับระบบที่ใช้ Business 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

สำหรับระบบที่ใช้ Business 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;
}
});

เรียนรู้เพิ่มเติม

• เกตเวย์ API คอนเวอร์ชั่น
• เกตเวย์ API คอนเวอร์ชั่นสำหรับหลายบัญชี
• พารามิเตอร์ API คอนเวอร์ชั่น
• หลักปฏิบัติที่ดีที่สุด