pooriaarab Baidu Ads
Baidu supports self-serve Search Promotion account opening. Its oCPC docs publish web JS tracking, a server conversion upload API, and separate app API and app SDK routes. See Baidu account opening, oCPC JS, and the oCPC index.
Use ad-conversion-hub for the canonical event envelope, consent gate, identity normalization, retry policy, and adapter contract. This skill records only Baidu-specific facts.
Account and access
Baidu's official account guide says advertisers can register, submit company information, upload required materials, prepay, and open an account through its self-serve flow. See Baidu account opening.
For web API tracking, the account administrator enables the oCPC entry, creates an API conversion tracker, and obtains its API code token. See Search Promotion setup and Feed Promotion setup.
The developer requests the API token from the Baidu promotion account administrator. A token reset takes effect immediately, so update the server configuration after each reset. See account token guidance.
Baidu's docs define the vendor fields token, production, bd_vid, conversionTypes, logidUrl, and newType. They define no environment variable names. Use these local names only as adapter conventions:
BAIDU_OCPC_TOKEN server-only token from the promotion administrator
BAIDU_OCPC_PRODUCTION public value from the Baidu web code
BAIDU_OCPC_BD_VID first-party storage for the captured bd_vid
BAIDU_OCPC_BD_VID is captured fresh per visitor and per landing page. Unlike
the other two names, it is not a single static deployment secret — never bind
one process-wide value and replay it on every logidUrl.
Do not treat these local names as Baidu configuration. The vendor-defined names appear in the web code and upload schema.
Baidu also publishes a general Promotion API and a developer center for API permission management. Use the product-specific oCPC contract for conversion work. See Baidu Promotion API.
Client-side oCPC JS SDK
Baidu's web route has a base SDK and conversion code. Install the base code in
the page <head> before adding a conversion call. See JS overview and base installation.
Copy the base code from the account's own oCPC console web-code page. Replace
production with the account's BAIDU_OCPC_PRODUCTION value everywhere it
appears, including the script URL query string — reusing Baidu's documentation
sample value attributes every conversion to Baidu's sample account instead of
the advertiser's:
<script>
window._agl = window._agl || [];
(function () {
_agl.push(['production', '<BAIDU_OCPC_PRODUCTION>']);
(function () {
var agl = document.createElement('script');
agl.type = 'text/javascript';
agl.async = true;
agl.src = 'https://fxgate.baidu.com/angelia/fcagl.js?production=<BAIDU_OCPC_PRODUCTION>';
var s = document.getElementsByTagName('script')[0];
s.parentNode.insertBefore(agl, s);
})();
})();
</script>
For a successful web form, call the documented success event after the
business operation succeeds. The documented form code uses type 3:
window._agl && window._agl.push(['track', ['success', { t: 3 }]]);
See form conversion code.
For a click conversion, add data-agl-cvt to the conversion element. Use only the code assigned to the account's configured click type. See click conversion codes.
Rule setup and event mapping
Create the conversion tracker in Baidu Promotion before sending events. Search uses API conversion tracking. Feed uses an API lead conversion tracker. See Search setup and Feed setup.
newType must match a conversion type exposed by the promotion account. Baidu's
published table includes these relevant codes:
| Hub event | Baidu type | Rule |
|---|---|---|
lead |
18 |
The published table calls this 留线索; confirm the account type. See type table. |
signup |
3 or 25 |
Use 3 for web form success; use 25 for app registration. See type table. |
purchase |
10 |
The published table calls this 购买成功; confirm the account type. See type table. |
subscription_start |
None listed | Keep first-party measurement unless the account exposes a supported type. See type table. |
refund |
None listed | Reconcile with payment truth; the published table has no refund row. See type table. |
Do not translate hub event names into undocumented Baidu strings. Send the account's numeric newType value. Baidu says each record selects one conversion type, and one click with two types needs two records. See upload schema.
Server-side conversions API
Baidu publishes an advertiser-server endpoint for matched oCPC conversions. It accepts JSON with a token and a conversionTypes array containing fewer than 100 records:
POST https://ocpc.baidu.com/ocpcapi/api/uploadConvertData
Content-Type: application/json
Use the documented fields. logidUrl carries the landing URL with bd_vid. newType carries the account conversion code:
{
"token": "<BAIDU_OCPC_TOKEN>",
"conversionTypes": [
{
"logidUrl": "https://example.com/thank-you?bd_vid=<BD_VID>",
"newType": 10
}
]
}
logidUrl is required and cannot exceed 1024 characters. newType is required for new integrations and replaces the older convertType field. See API fields.
The documented optional fields are deviceType, deviceId, isConvert, convertTime, convertValue, and confidence. deviceType uses 0 for Android, 1 for iOS, and 2 for other devices. convertTime uses Unix seconds. convertValue uses fen. See record fields.
Read header.status from every response. Baidu defines 0 as success, 1 as partial success, 2 as total failure, 3 as token failure, and 4 as server error. See response statuses.
Retry only failures the hub can safely replay. Status 2 (total failure) and status 3 (token failure) are safe to retry under the hub's bounded policy once the underlying cause is fixed, since the documented response codes for those cases mean the record was rejected outright. Status 4 (server error) is ambiguous like a transport failure — Baidu's own docs do not guarantee the record was not persisted before the error was raised, and the checked schema defines no dedup key — so treat status 4 the same as a missing response: unknown, and dead-lettered for reconciliation instead of retried. Record failed positions from a partial response before retrying. See Baidu sample and ad-conversion-hub.
The checked web upload schema has no email, phone, browser identity, event ID, or browser/server deduplication field. Do not add any. Use the hub's local dispatch record for idempotency. See upload schema.
App conversion routes
Baidu documents two app collection routes. The app API sends click data to the advertiser or a monitoring platform, which matches app conversions and reports them back to Baidu at the fixed, documented callback host below. The app SDK uploads app events to Baidu directly. See app collection overview.
Treat the inbound callback_url field as untrusted input, not as a destination to call blindly: validate that its scheme, host, and path match the fixed ocpc.baidu.com /ocpcapi/cb/actionCb endpoint shown below, and drop the record if they do not — a forged click could otherwise point it at an internal address (SSRF). Once validated, keep its s and ext_info query values exactly as received; they are the click-specific identifiers Baidu needs to match the conversion, and rebuilding the URL from scratch without them causes a valid conversion to go unattributed. Only a_type, a_value, and sign are yours to add.
For app API traffic, the documented monitoring request can include idfa, imei_md5, oaid, click_id, and callback_url. Baidu defines imei_md5 as lowercase MD5 of the original IMEI, while idfa and oaid remain raw values. See app API parameters.
The documented callback URL is:
GET http://ocpc.baidu.com/ocpcapi/cb/actionCb?a_type=<ATYPE>&a_value=<AVALUE>&s=<S>&ext_info=<EXT_INFO>&sign=<SIGN>
Replace a_type and a_value using the app conversion. The activation example uses a_type=activate and a_value=0. Compute sign as the standard lowercase MD5 of the complete callback URL without &sign= followed by the account's akey. See callback interface and activation guide.
The official callback example uses HTTP. Confirm transport requirements with Baidu for the enabled app product before production. See callback interface.
For app SDK tracking, apply for an SDK application ID, embed Baidu's SDK, and create the app SDK conversion tracker in the promotion console. Baidu's SDK guide lists app start, duration, activation, registration, and payment as required reports. See app SDK setup.
The app SDK guide documents REGISTER and PURCHASE actions. Its purchase example reports money in fen. Follow the platform SDK guide for implementation.
Identity and consent
The checked web upload schema documents device fields, but it does not define an email field, phone field, or consent parameter. Do not invent a web hashing rule or consent parameter. Use the hub's consent gate and identity normalization. See upload fields and ad-conversion-hub.
For app API callbacks, send only documented device fields that the hub permits.
Baidu documents raw idfa, raw oaid, and lowercase MD5 imei_md5. See app
API parameters.
Click ID and first-party cookie
After API conversion tracking is enabled, Baidu appends bd_vid to promoted
landing URLs. Search uses API conversion tracking. Feed uses the lead API route.
See landing URL guidance.
Baidu says bd_vid becomes effective about 90 minutes after tracking is enabled.
Each ad click receives a different value. See bd_vid behavior.
Capture bd_vid on the first landing request. Preserve it through redirects and
later conversion pages. Baidu documents three propagation methods: read the
referer, store it in a cookie, or append it to the next URL. See URL propagation.
Baidu does not name a required cookie in the checked docs. Use consented,
first-party storage under the local convention BAIDU_OCPC_BD_VID. Send the
full landing URL as logidUrl, not only the bare ID. See logidUrl rules.
Do not block the hub event when bd_vid is absent. Preserve the business event,
then mark the Baidu dispatch as skipped when no matchable landing URL exists.
See ad-conversion-hub.
Deduplication
Baidu's checked web upload schema defines no event ID and no browser/server
deduplication contract. Do not send guessed event_id or eventId fields. See
upload schema.
Use the hub event ID in local dispatch records. Key retry decisions by the event
ID, captured bd_vid, and account newType. Send separate records when one
click maps to multiple conversion types. See upload schema
and ad-conversion-hub.
Promotion console settings that override code
The account administrator must enable the oCPC entry and create the matching API conversion tracker before API data can be checked. See Search setup and Feed setup.
If an account used JS reporting before API setup, Baidu says the JS can remain. Change the promotion backend's data source to API reporting. See account FAQ.
The conversion type configured in Promotion must match the JS code or server
newType. Baidu says a mismatch prevents collection. See data troubleshooting.
Verification
Verify the web base code in browser developer tools. Find a request beginning
with http://fclog.baidu.com/log/ocpcagl and confirm status 200. Baidu uses
those checks to verify base-code installation. See base-code verification.
Verify the form call at the successful submission branch. Baidu's guide says to confirm the agl.push call exists. See form verification.
For server uploads, record the redacted response and inspect header.status. Status 0 proves upload acceptance only. It does not prove filtered reporting or campaign credit. See API response.
Use the Baidu oCPC Developer Center to query raw API returns and download the details. Baidu says promotion reports filter raw data, so the counts can differ. See Search reconciliation and data reconciliation.
Baidu's report guidance says promotion conversion reports lag by one day. Compare raw returns, filtered reports, and the hub source event. See report timing.
Common pitfalls and security
- Keep
bd_vidthrough redirects and later conversion pages. See Baidu URL guidance. - Keep
logidUrlunder 1024 characters and send the full URL. See API fields. - Use
newTypefor new web API integrations. See API fields. - Treat partial status as partial and inspect each returned error position. See API responses.
- Replace the stored token after an administrator resets it. See account FAQ.
- Do not send undocumented email, phone, event ID, or browser deduplication fields. See upload schema.
- Keep tokens,
akey, and device identifiers server-side. Do not log or commit them. See API access and app API parameters. - Keep payment and signup flows independent from Baidu. A missing Baidu match must not fail the business event. See ad-conversion-hub.
- Never call an outbound URL taken from inbound click or monitoring data. Call only the fixed, documented
ocpc.baidu.comcallback host. See callback interface.
Official sources checked (2026-08-29)
- Baidu account opening · Baidu Promotion API · oCPC index
- JS overview · base code · form code
- Click codes · conversion types
- Search setup · Feed setup · upload interface
- Account FAQ · landing URL guidance · data troubleshooting · data reconciliation
- App overview · app callback · activation guide · app SDK