API Chuyển đổi

Sử dụng API

Sau khi bạn hoàn thành các điều kiện tiên quyết trên trang Bắt đầu, hãy tham khảo trang này để tìm hiểu cách gửi sự kiện và sử dụng công cụ Thử nghiệm sự kiện. Sau khi bạn gửi sự kiện, hãy xác minh cách thiết lập.

API Chuyển đổi dựa trên API Marketing của Facebook, được xây dựng trên API Đồ thị. API Đồ thị và API Marketing có lịch ngừng sử dụng phiên bản khác nhau. Chu kỳ phát hành của chúng tôi phù hợp với API Đồ thị. Vì vậy, mọi phiên bản đều được hỗ trợ trong ít nhất 2 năm. Ngoại lệ này chỉ dành cho API Chuyển đổi.

API Chuyển đổi: Tổng quanThông số

Những sự kiện trên web, trong ứng dụng và ở cửa hàng thực được chia sẻ bằng API Chuyển đổi cần có các thông số cụ thể. Bằng cách sử dụng API Chuyển đổi, bạn đồng ý rằng thông số action_source là chính xác theo hiểu biết của bạn. Bạn có thể xem danh sách các thông số bắt buộc ở đây.

Gửi yêu cầu

Để gửi sự kiện mới, hãy gửi yêu cầu POST đến cạnh /events của API này từ đường dẫn sau: https://graph.facebook.com/{API_VERSION}/{PIXEL_ID}/events?access_token={TOKEN}. Khi bạn đăng lên cạnh này, Facebook sẽ tạo sự kiện mới trên máy chủ.

curl -X POST \
  -F 'data=[
       {
         "event_name": "Purchase",
         "event_time": 1715938591,
         "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

Hãy đính kèm mã truy cập an toàn đã tạo của bạn bằng thông số truy vấn access_token vào yêu cầu. Bạn cũng có thể sử dụng Trình khám phá API Đồ thị để gửi yêu cầu POST đến điểm cuối /<pixel_id>/events.

Phần nội dung của yêu cầu mẫu sẽ có dạng như sau:

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

Thời điểm tải lên so với thời điểm giao dịch của sự kiện

event_time là thời điểm giao dịch của sự kiện. Bạn nên gửi thông số này dưới dạng nhãn thời gian Unix tính bằng giây (cho biết thời điểm sự kiện thực tế diễn ra). Thời điểm đã chỉ định này có thể sớm hơn thời điểm bạn gửi sự kiện cho Facebook. Nhờ thế, hệ thống có thể xử lý hàng loạt và tối ưu hóa hiệu quả của máy chủ.

event_time có thể sớm hơn thời điểm bạn gửi sự kiện cho Meta tối đa 7 ngày. Nếu bất kỳ event_time nào trong data sớm hơn thời điểm bạn gửi quá 7 ngày, chúng tôi sẽ trả về lỗi đối với toàn bộ yêu cầu và không xử lý sự kiện nào. Đối với sự kiện offline và sự kiện tại cửa hàng thực có physical_store là action_source, bạn nên tải giao dịch lên trong vòng 62 ngày kể từ ngày chuyển đổi.

Bằng cách sử dụng API Chuyển đổi, bạn đồng ý rằng thông số action_source là chính xác theo hiểu biết của bạn.

Yêu cầu hàng loạt

Bạn có thể gửi tối đa 1.000 sự kiện trong data. Tuy nhiên, để đạt hiệu quả tối ưu, bạn nên gửi ngay khi sự kiện diễn ra và tốt hơn hết là trong vòng 1 giờ kể từ khi sự kiện diễn ra. Nếu trong loạt sự kiện bạn gửi có bất kỳ sự kiện nào không hợp lệ, chúng tôi sẽ từ chối toàn bộ loạt sự kiện đó.

Băm

Vui lòng xem trang thông số thông tin khách hàng của chúng tôi để biết nên băm những thông số nào trước khi gửi cho Facebook. Nếu bạn đang sử dụng một trong những Business SDK của chúng tôi, SDK sẽ thực hiện việc băm giúp bạn.

Tính năng của Business SDK dành cho API Chuyển đổi

Tìm hiểu thêm về 3 tính năng cụ thể của Business SDK dành riêng cho người dùng API Chuyển đổi: Yêu cầu không đồng bộ, Tạo nhóm đồng thời và Giao diện dịch vụ HTTP. Sau đây là phiên bản ngôn ngữ tối thiểu cần có để sử dụng các tính năng này:

  • PHP 7.2 trở lên
  • Node.js 7.6.0 trở lên
  • Java 8 trở lên
  • Python 2.7 trở lên
  • Ruby 2 trở lên

Business SDK hỗ trợ PHP 5 đã ngừng hoạt động kể từ tháng 01/2019. Vui lòng nâng cấp lên PHP 7 để sử dụng Business SDK.

Nếu bạn phải sử dụng PHP 5, hãy cân nhắc dùng quy trình triển khai Swagger của chúng tôi.

Thông số API Chuyển đổi

Xác minh sự kiện

Sau khi bạn gửi sự kiện, hãy xác nhận rằng chúng tôi đã nhận được các sự kiện đó trong Trình quản lý sự kiện:

  • Trên trang Nguồn dữ liệu, hãy nhấp vào Pixel tương ứng với PIXEL_ID trong yêu cầu POST của bạn. Để biết thêm thông tin, hãy xem bài viết trong Trung tâm trợ giúp doanh nghiệp: Điều hướng trong Trình quản lý sự kiện.
  • Sau đó, nhấp vào phần Tổng quan. Bạn sẽ thấy số lượng sự kiện chưa xử lý, đã so khớp và đã phân bổ mà chúng tôi nhận được. Trong phần Phương thức kết nối, bạn sẽ thấy kênh đã gửi sự kiện đó.
  • Bạn có thể nhấp vào từng sự kiện để xem thêm thông tin cụ thể.
  • Sau khi bắt đầu gửi sự kiện, bạn sẽ có thể xác minh sự kiện trong vòng 20 phút. Bây giờ, bạn có thể bắt đầu gửi sự kiện từ máy chủ của mình.

Công cụ Thử nghiệm sự kiện

Bạn có thể xác minh để đảm bảo rằng Facebook đã nhận được chính xác sự kiện từ máy chủ của bạn thông qua tính năng Thử nghiệm sự kiện trong Trình quản lý sự kiện. Để tìm công cụ này, bạn hãy chuyển đến Events Manager > Data Sources > Your Pixel > Test Events.

Công cụ Thử nghiệm sự kiện sẽ tạo một ID thử nghiệm. Hãy gửi ID thử nghiệm này dưới dạng thông số test_event_code để bắt đầu xem hoạt động trong sự kiện xuất hiện ở cửa sổ Thử nghiệm sự kiện.

Lưu ý: Bạn chỉ nên dùng trường test_event_code để thử nghiệm. Bạn cần gỡ trường này khi gửi phần tải dữ liệu chính thức.

Sự kiện gửi bằng test_event_code sẽ không bị bỏ dở. Sự kiện đó sẽ chuyển vào Trình quản lý sự kiện và được dùng cho mục đích nhắm mục tiêu cũng như đo lường quảng cáo.

Dưới đây là ví dụ về cấu trúc của yêu cầu:

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

Còn đây là ví dụ về giao diện của yêu cầu trong Trình khám phá API Đồ thị:

Bạn có thể tạo phần tải dữ liệu thử nghiệm này bằng Công cụ hỗ trợ phần tải dữ liệu. Lưu ý rằng mã sự kiện thử nghiệm này chỉ dùng để thử nghiệm phần tải dữ liệu.

Sự kiện trên máy chủ của bạn sẽ hiển thị trong cửa sổ Thử nghiệm sự kiện sau khi bạn gửi yêu cầu.

Tùy chọn xử lý dữ liệu cho người dùng tại Hoa Kỳ

Đối với 2 API này, hãy triển khai tùy chọn xử lý dữ liệu bằng cách thêm data_processing_options, data_processing_options_country và data_processing_options_state vào mỗi sự kiện trong thông số dữ liệu của sự kiện.

Lưu ý: API Sự kiện trong ứng dụng và API Chuyển đổi offline không còn được khuyến nghị cho tiện ích tích hợp mới nữa. Thay vào đó, bạn nên sử dụng API Chuyển đổi vì API này hỗ trợ sự kiện trên web, sự kiện trong ứng dụng và sự kiện offline. Hãy xem API Chuyển đổi cho Sự kiện trong ứng dụng và API Chuyển đổi cho Sự kiện offline để biết thêm thông tin.

Để rõ ràng không bật tính năng Giới hạn mức sử dụng dữ liệu (LDU), hãy chỉ định một mảng trống cho từng sự kiện hoặc chỉ cần gỡ trường này trong phần tải dữ liệu:

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

Để bật tính năng LDU và yêu cầu Meta xác định vị trí địa lý:

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

Để bật tính năng LDU và chỉ định vị trí theo cách thủ công, chẳng hạn như cho California:

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

Giao diện người dùng tải lên thủ công

API Chuyển đổi offline có tùy chọn tải lên thủ công các sự kiện từ file .csv. Trong trường hợp này, hãy thêm các cột Tùy chọn xử lý dữ liệu, Quốc gia xử lý dữ liệu và Tiểu bang xử lý dữ liệu trong file của bạn. Bạn có thể tìm thêm thông tin về điều này trong giao diện người dùng tải lên.


Tìm hiểu thêm về Tùy chọn xử lý dữ liệu.

Các giới hạn về API

API Marketing có logic giới hạn tốc độ riêng và không thuộc bất kỳ giới hạn tốc độ nào của API Đồ thị. Do đó, nếu bạn thực hiện lệnh gọi API Marketing, lệnh gọi đó sẽ không được tính vào giới hạn của API Đồ thị.

API Chuyển đổi không có giới hạn tốc độ cụ thể. Lệnh gọi API Chuyển đổi được tính là lệnh gọi API Marketing. Giới hạn duy nhất là mỗi lần, bạn chỉ có thể gửi tối đa 1.000 sự kiện. Hãy xem phần Gửi yêu cầu để biết thêm thông tin.

Giới hạn tốc độ của API Marketing

Sử dụng API Business SDK trong Cổng API Chuyển đổi

Hướng dẫn này giúp bạn khám phá các tính năng nâng cao của Meta Business SDK dành riêng cho người dùng Cổng API Chuyển đổi. Nếu bạn muốn biết cách sử dụng Cổng API Chuyển đổi cơ bản, hãy tham khảo tài liệu về Cổng API Chuyển đổi.

Gửi sự kiện đến phiên bản Cổng API Chuyển đổi

Yêu cầu

Trước khi sử dụng bất kỳ tính năng nào nêu dưới đây, bạn cần cài đặt Meta Business SDK. Hãy xem bài viết Bắt đầu sử dụng Meta Business SDK hoặc làm theo hướng dẫn trong file README theo liên kết dưới đây:

Hiện tại, những tính năng này chỉ dùng được trên Business SDK dành cho PHP và Java. Các ngôn ngữ khác sẽ được triển khai muộn nhất vào cuối năm 2023.

Sau đây là phiên bản ngôn ngữ tối thiểu cần có để sử dụng các tính năng này:

PHP 7.2 trở lên

Java 8 trở lên

Lưu ý: Để bỏ trùng lặp sự kiện đến điểm cuối API Chuyển đổi, vui lòng chuyển eventId vào yêu cầu của bạn. Như vậy, các sự kiện trùng lặp sẽ không hiển thị nếu bạn bật tính năng đăng API Chuyển đổi.

Định dạng thông số CAPIGatewayIngressRequest

Thông sốMô tả
endpointUrl
chuỗi

Điểm cuối Cổng API Chuyển đổi mà các sự kiện được gửi đến. Hệ thống sẽ không xác thực trước thông số ngoài việc kiểm tra xem đó có phải là URL hợp lệ hay không.


Ví dụ: https://test.example.com


accessKey
chuỗi

Khóa truy cập Cổng API Chuyển đổi cần có để gửi sự kiện đến điểm cuối sự kiện Cổng API Chuyển đổi. Đây là những hướng dẫn để tạo khóa này.

Phương thức setter CAPIGatewayIngressRequest

Thông sốMô tả
setSendToDestinationOnly
Boolean

Cờ boolean cho biết liệu hệ thống có chỉ gửi sự kiện đến điểm cuối đã chọn hay không.


Giá trị mặc định: False


setFilter
Hàm CustomEndpointRequest.Filter()

Hàm lọc xử lý từng sự kiện. Nếu logic lọc trả về giá trị true, sự kiện sẽ được chuyển qua. Nếu không, sự kiện sẽ bị hủy. Bạn phải triển khai hàm shouldSendEvent trên giao diện có thông số Event.


Giá trị mặc định: Null



Ví dụ về việc chuyển: PHP

Đối với những hệ thống đã sử dụng Business SDK, bạn chỉ cần tham chiếu CAPIGatewayIngressRequest mới rồi đính kèm yêu cầu này vào đối tượng customEndpoint của 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()

Ví dụ về việc chuyển: Java

Đối với những hệ thống đã sử dụng Business SDK, bạn chỉ cần tham chiếu CAPIGatewayIngressRequest mới rồi đính kèm yêu cầu này vào đối tượng customEndpoint của 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();

Tùy chọn đồng bộ

Mã PHP mẫu

$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());

Mã Java mẫu

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();

Tùy chọn không đồng bộ

Mã PHP mẫu

$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();

Mã Java mẫu

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();

Chức năng lọc

Mã PHP mẫu

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());

Mã Java mẫu

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;
}
});

Tìm hiểu thêm