3: Quy trình triển khai dành cho nhà phát triển

Trang này hướng dẫn cách tích hợp thủ công, bao gồm các bước sau đây:

Tạo phần tải dữ liệu cho quá trình tích hợp CRM
Tạo mã truy cập và chuẩn bị lệnh gọi API
Gửi phần tải dữ liệu thử nghiệm
Gửi dữ liệu sản xuất

Phần này chỉ áp dụng khi bạn quyết định tích hợp thủ công và sử dụng tài nguyên dành cho nhà phát triển. Nếu bạn quyết định tích hợp qua đối tác, hãy làm theo hướng dẫn tích hợp tương ứng của đối tác. Bạn có thể chuyển đến phần 4: Xác minh dữ liệu trong hướng dẫn này sau khi quá trình tích hợp đối tác hoàn tất.

Bạn sẽ cần có quyền truy cập của quản trị viên Trình quản lý kinh doanh để hoàn tất các bước tích hợp dưới đây. Bạn có thể lấy quyền truy cập từ email mình nhận được nếu bạn được mời làm nhà phát triển. Nếu không, hãy liên hệ với quản trị viên Trình quản lý kinh doanh để yêu cầu quyền truy cập.

Bước 1: Tạo phần tải dữ liệu

Bước này sẽ trình bày quy cách phần tải dữ liệu cho quá trình tích hợp Khách hàng có tiềm năng chuyển đổi, đồng thời đưa ra một số đề xuất về cách gửi quy cách đó từ máy chủ của bạn.

Mở hướng dẫn tích hợp CRM ở tab Cài đặt của Pixel CRM để bắt đầu.

Xem lại Hướng dẫn về API Chuyển đổi dành cho nhà phát triển để hiểu cách hoạt động của API Chuyển đổi.

Bạn nên tạo phần tải dữ liệu bằng Trình trợ giúp phần tải dữ liệu. Trình trợ giúp phần tải dữ liệu này sẽ định dạng phần tải dữ liệu của bạn và kiểm tra lỗi. Sau khi bạn xử lý mọi lỗi phần tải dữ liệu, hãy nhấp vào nút Lấy mã bên trong Trình trợ giúp phần tải dữ liệu để tạo mẫu mã cho ngôn ngữ lập trình của bạn.

Sau đây là danh sách các thông số bắt buộc. Hãy xem nội dung mô tả đầy đủ cho mỗi thông số trong hướng dẫn Tích hợp khách hàng có tiềm năng chuyển đổi - Quy cách phần tải dữ liệu. Bạn chỉ nên sử dụng quy cách phần tải dữ liệu này cho sự kiện Tối ưu hóa khách hàng có tiềm năng chuyển đổi. Tức là sự kiện chỉ nên liên quan đến quảng cáo tìm kiếm khách hàng tiềm năng trên Meta và có ID khách hàng tiềm năng hợp lệ. Không sử dụng quy cách phần tải dữ liệu này cho các loại sự kiện khác, chẳng hạn như khách hàng tiềm năng trên trang web.

Thông số

Tên	Mô tả
`event_name` chuỗi	Trường dạng tự do để ghi lại các giai đoạn khách hàng tiềm năng mà bạn sử dụng trong CRM. Thông số `event_name` sẽ cho biết khách hàng tiềm năng đang di chuyển qua phễu bán hàng trong CRM của bạn. Hãy đảm bảo gửi tất cả giai đoạn khi có cập nhật, bao gồm cả giai đoạn khách hàng tiềm năng thô.
`event_time` số nguyên	Nhãn thời gian Unix tính bằng giây, cho biết thời điểm CRM của bạn cập nhật sự kiện cập nhật giai đoạn khách hàng tiềm năng. Nhãn thời gian này phải sau thời điểm tìm kiếm khách hàng tiềm năng. Nếu không, sự kiện có thể bị bỏ.
`action_source` chuỗi	Giá trị:`system_generated` (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.)
`lead_id` số nguyên	`leadgen_id` gồm 15 hoặc 16 chữ số từ dữ liệu khách hàng tiềm năng bạn đã tải xuống.
`lead_event_source` chuỗi	Tên của CRM gửi sự kiện.
`event_source` chuỗi	Giá trị:`crm`

Ví dụ
Phần tải dữ liệu mẫu có dạng như sau. Lưu ý: Bạn phải sử dụng lead_id hợp lệ. Nếu không, hệ thống sẽ từ chối sự kiện của bạn.

{
    "data": [
        {
            "event_name": "initial_lead",
            "event_time": 1629424350,
            "action_source": "system_generated",
            "user_data": {
                "lead_id": 525645896321548
            },
            "custom_data": {
                "event_source": "crm",
                "lead_event_source": "salesforce"
            }
        }
    ]
}

Nếu sự kiện không tuân theo quy cách phần tải dữ liệu hoặc không khớp với quảng cáo tìm kiếm khách hàng tiềm năng trên Meta, hệ thống sẽ không nhận diện được sự kiện cho quá trình tích hợp và không sử dụng sự kiện đó để huấn luyện mô hình.
Ví dụ: phần tải dữ liệu Web sẽ được API Chuyển đổi chấp nhận và xuất hiện trong Trình quản lý sự kiện, nhưng sẽ không được nhận diện cho quá trình tích hợp này. Bạn cũng phải sử dụng lead_id hợp lệ. Nếu không, hệ thống sẽ từ chối sự kiện của bạn.
Chỉ phần tải dữ liệu Khách hàng có tiềm năng chuyển đổi mới được nhận diện cho quá trình tích hợp và được dùng để huấn luyện.

Bước 2: Tạo mã truy cập và lệnh gọi API

Sau khi bạn đặt cấu hình dữ liệu mình sẽ gửi, bước tiếp theo là đặt cấu hình vị trí bạn sẽ gửi dữ liệu.

Bước này sẽ giúp bạn tạo mã truy cập cho Meta Pixel. Sau đó, bạn sẽ dùng mã này để thiết lập kết nối giữa máy chủ của mình và API Chuyển đổi.

Bạn có thể quay lại hướng dẫn tích hợp CRM ở tab Cài đặt của Pixel CRM.

Cuộn xuống phần Tạo điểm cuối rồi nhấp vào nút Tạo mã truy cập. Mã truy cập này sẽ được dùng để tạo lệnh gọi API.
Bạn có thể tạo mã truy cập mới bằng cách quay lại hướng dẫn tích hợp hoặc chuyển đến phần API Chuyển đổi ở tab Cài đặt trong Trình quản lý sự kiện, rồi nhấp vào liên kết Tạo mã truy cập.

Phần còn lại của hướng dẫn này sẽ khác nhau tùy theo việc bạn có sử dụng SDK của Meta hay không. Bạn nên sử dụng Meta Business SDK vì SDK này cung cấp thông báo lỗi và chẩn đoán tốt hơn. Bạn sẽ cần có ID Pixel và mã truy cập để thực hiện lệnh gọi API qua Meta Business SDK. Bạn có thể lấy mã truy cập bằng cách nhấp vào Sao chép mã truy cập trong hướng dẫn tích hợp CRM rồi lưu mã này. Bạn có thể tìm thấy ví dụ về lệnh gọi API SDK trong Hướng dẫn về API Chuyển đổi dành cho nhà phát triển hoặc chức năng Lấy mã trong Trình trợ giúp phần tải dữ liệu của Meta.

Đây là định dạng điểm cuối để gửi yêu cầu POST đến API Chuyển đổi mà không cần SDK. Bạn có thể lấy toàn bộ điểm cuối bằng cách nhấp vào Sao chép điểm cuối trong hướng dẫn tích hợp CRM rồi lưu điểm cuối này.
```
https://graph.facebook.com/API_VERSION/PIXEL_ID/events?access_token=ACCESS_TOKEN
```
- API_VERSION: Phiên bản API Marketing hiện tại
- PIXEL_ID: ID Pixel mà bạn có thể lấy từ Trình quản lý sự kiện cho mỗi Pixel
- ACCESS_TOKEN: Mã truy cập được tạo ở trên
Bạn có thể xem ngày phát hành và ngày hết hạn của API Marketing trong tài liệu về Phiên bản API. Hãy nhớ cập nhật phiên bản API hoặc Meta Business SDK trong mã của bạn trước ngày hết hạn của API Marketing. Nếu sử dụng phiên bản đã ngừng hoạt động trong mã, bạn có thể gặp lỗi và hệ thống có thể bỏ sự kiện của bạn.

Bước 3: Thử nghiệm phần tải dữ liệu (không bắt buộc)

Lúc này, bạn có thể muốn gửi phần tải dữ liệu thử nghiệm đến Pixel của mình trước khi triển khai mã trên máy chủ. Bạn có thể làm như vậy thông qua tab Thử nghiệm sự kiện trong Trình quản lý sự kiện.

Trong phần Thử nghiệm sự kiện trên máy chủ, nhấp vào liên kết Trình khám phá API Đồ thị. Khi bạn sử dụng liên kết duy nhất này, hệ thống sẽ điền sẵn một số thông tin từ Pixel của bạn. (Nếu muốn, bạn cũng có thể truy cập trực tiếp vào Trình khám phá API Đồ thị.) Hãy ghi lại giá trị test_event_code. Giá trị này có thể thay đổi theo thời gian.

Hoàn tất các bước sau đây trong công cụ Trình khám phá API Đồ thị:
1. Đảm bảo rằng bạn ở chế độ POST.
2. Kiểm tra để đảm bảo rằng phiên bản API và ID Pixel của bạn chính xác.
3. Chuyển sang chế độ xem JSON.
4. Nhập phần tải dữ liệu của bạn. Bạn có thể tạo phần tải dữ liệu này theo cách thủ công hoặc tạo bằng Trình trợ giúp phần tải dữ liệu. Đảm bảo thêm thông số test_event_code ở bước trước và lead_id hợp lệ.
Nhập mã truy cập Pixel của bạn rồi nhấp vào nút Gửi.

Nếu phần tải dữ liệu của bạn không có lỗi cú pháp hay lỗi API nào, bạn sẽ nhận được thông báo thành công cùng fbtrace_id.

Sự kiện thử nghiệm sẽ xuất hiện ở tab Thử nghiệm sự kiện trong Trình quản lý sự kiện sau một thời gian ngắn.

Bước 4: Gửi dữ liệu sản xuất

Dữ liệu sản xuất phải có cùng định dạng với phần tải dữ liệu được tạo ở Bước 3, ngoại trừ dữ liệu mà máy chủ của bạn sẽ gửi trực tiếp. Bước này sẽ khác nhau đối với mỗi quá trình tích hợp. Vì vậy, phần này sẽ đưa ra nguyên tắc chứ không phải hướng dẫn từng bước.

Gửi lead_id thay vì PII để so khớp.

Đảm bảo gửi tất cả giai đoạn khách hàng tiềm năng khi có cập nhật, bao gồm cả sự kiện khách hàng tiềm năng thô biểu thị mọi khách hàng tiềm năng tìm kiếm được trên Meta và được tải xuống CRM của bạn. Dưới đây là phễu mẫu. Tên sự kiện và giai đoạn là do nhà quảng cáo xác định nên không phải tuân theo ví dụ này.

Nếu chiến dịch của bạn tìm kiếm được 100 khách hàng tiềm năng, chúng tôi dự kiến sẽ tải 100 sự kiện "Khách hàng tiềm năng thô" lên để biểu thị giai đoạn khách hàng tiềm năng đầu tiên. Khi bạn gửi giai đoạn khách hàng tiềm năng đầu tiên, hệ thống sẽ biết là đã nhận và xử lý dữ liệu khách hàng tiềm năng. Khi khách hàng tiềm năng di chuyển xuống phễu bán hàng, chúng tôi dự kiến sẽ tải lên 70 giai đoạn "Khách hàng tiềm năng đủ điều kiện marketing", 30 giai đoạn "Cơ hội bán hàng" và 15 giai đoạn "Đã chuyển đổi".

Tóm lại, trong trường hợp mẫu này, chúng tôi dự kiến sẽ tải 215 sự kiện lên từ 100 khách hàng tiềm năng tìm kiếm được trong chiến dịch.

Tạo một hàm để truy xuất thông tin mới từ API hoặc cơ sở dữ liệu của CRM mỗi khi trạng thái khách hàng tiềm năng có cập nhật. Sau đó, hãy gửi phần tải dữ liệu của bạn đến API Chuyển đổi của Meta bằng một hàm tùy chỉnh hoặc Business SDK của Meta. Cách tích hợp phù hợp nhất sẽ phụ thuộc vào cấu hình CRM và cơ sở dữ liệu của bạn.

Các biến được khuyên dùng:
- lead_id
- event_name
- event_time
Ví dụ: phần tải dữ liệu nêu rõ các giá trị thông số có thể có dạng như sau:
```
{
  "event_name": "initial_lead",
  "event_time": 1628294742,
  "user_data": {
    "lead_id": 1234567890123456
  },
  "action_source": "system_generated",
  "custom_data:" {
    "lead_event_source": "Salesforce",
    "event_source": "crm"
  }
}
```
Phần tải dữ liệu dùng biến để chuyển giá trị từ cơ sở dữ liệu của bạn có thể có dạng như sau:
```
{
  "event_name": lead_stage // "initial_lead"
  "event_time": unix_time // 1628294742
  "user_data": {
    "lead_id": fb_lead_id // 1234567890123456
  },
  "action_source": "system_generated",
  "custom_data:" {
    "lead_event_source": "Salesforce",
    "event_source": "crm"
  }
}
```

Tải dữ liệu lên ít nhất một lần mỗi ngày. Lý tưởng là bạn nên thực hiện lệnh gọi đến CRM của mình theo thời gian thực. Tuy nhiên, bạn có thể sử dụng phương thức phân lô theo giờ hoặc theo ngày nếu việc tích hợp theo thời gian thực không khả thi.
Nếu bạn chọn phương thức phân lô, hãy đảm bảo rằng bạn ghi lại lịch sử thay đổi trạng thái khách hàng tiềm năng, chứ không phải phiên bản của khách hàng tiềm năng tại thời điểm phân lô. Ví dụ: nếu trạng thái của khách hàng tiềm năng cập nhật 3 lần giữa các lô, chúng tôi dự kiến sẽ có 3 sự kiện cho khách hàng tiềm năng này, chứ không chỉ lần cập nhật cuối cùng.
Lưu ý: Mỗi lô có thể bao gồm tối đa 1.000 sự kiện. Nếu lô có lỗi, toàn bộ lô sẽ bị bỏ. Vì vậy, bạn NÊN sử dụng lô nhỏ hơn và thêm logic cho các lần thử lại.

Không bắt buộc. Bạn nên ghi lại thông báo lỗi từ lệnh gọi CAPI và tạo thông báo nếu có vấn đề. Việc xử lý ngoại lệ cho những lỗi này cũng sẽ là một ý hay.

Bạn có thể bổ sung dữ liệu cũ cho dữ liệu của mình trong tối đa 7 ngày trước. Chênh lệch thời gian được tính giữa event_time và upload_time. Việc bổ sung dữ liệu cũ cho một số dữ liệu có thể đẩy nhanh quá trình huấn luyện.
CẢNH BÁO: Không cố bổ sung dữ liệu cũ hơn 7 ngày bằng cách sửa đổi giá trị event_time. Mô hình này tối ưu hóa dựa trên nhãn thời gian chính xác. Khi bạn làm như vậy, tất cả dữ liệu bạn đã bổ sung dữ liệu cũ có thể bị bỏ.
Đảm bảo rằng giá trị event_time sau nhãn thời gian tìm kiếm khách hàng tiềm năng. Nếu không, sự kiện của bạn có thể bị bỏ.

Nếu quá trình tích hợp của bạn đang tải sự kiện lên Meta, bạn sẽ bắt đầu thấy sự kiện xuất hiện trong Trình quản lý sự kiện cho Pixel của mình trong vòng một giờ. Hãy nhớ sử dụng lead_id hợp lệ trong phần tải dữ liệu thì sự kiện mới xuất hiện. Mở từng sự kiện được gửi cho quá trình tích hợp CRM Khách hàng có tiềm năng chuyển đổi trong Trình quản lý sự kiện, đồng thời kiểm tra để đảm bảo thông số tùy chỉnh lead_event_source và event_source đã được điền cho sự kiện. Nếu không có những thông số này, sự kiện sẽ không được đăng ký là sự kiện Khách hàng có tiềm năng chuyển đổi.
Hệ thống sẽ xác minh xem bất kỳ sự kiện nào của bạn có phải là sự kiện Khách hàng có tiềm năng chuyển đổi hợp lệ hay không. Sau 1 ngày, dấu kiểm màu xanh lá cây sẽ xuất hiện bên cạnh bước Gửi sự kiện CRM trong quá trình tích hợp nếu phát hiện thấy sự kiện hợp lệ.

< 2: Getting Started With the CRM Integration

4: Xác minh dữ liệu >