Skip to content

Commit 54bc252

Browse files
Jiaming Youmeta-codesync[bot]
authored andcommitted
Add Conversions API + Parameter Builder integration sections to READMEs
Summary: Document the Conversions API (CAPI) and the CAPI Parameter Builder integration in all five Business SDK READMEs (PHP, NodeJS, Java, Python, Ruby). The Java/NodeJS/Python/Ruby release READMEs are codegen-generated from codegen/templates/<lang>/README.md, so the new content is added to BOTH the templates and the generated release files (kept in sync so codegen.sh is a no-op). The PHP release README is hand-maintained (no template) and edited directly. Each README gains: - A "Conversions API" section: a basic end-to-end server-side event send (UserData + CustomData + Event + EventRequest.execute), plus a link to the advanced features guide (async, concurrent batching, custom HTTP service). - A "Conversions API Parameter Builder integration" subsection: setRequestContext / set_request_context auto-fills empty event fields from the incoming HTTP request (fbc, fbp, event_source_url, referrer_url), the optional Preference allowlist, and the non-destructive + order-independent behavior. The description of what request object to pass links to the "Framework support" section of the matching capi-param-builder GitHub README. Per-language accuracy matches the shipped code: - PHP & NodeJS also document client_ip_address auto-fill and automatic PII normalization + SHA-256 hashing. - Java, Python, Ruby note that client_ip_address is not auto-derived yet and should still be set manually. Depends on D107207093 Reviewed By: satwikareddy3, xuanjie22 Differential Revision: D108471483 fbshipit-source-id: f3f64ecbd9107bdd41b3c19e8b347821e87889fe
1 parent 3ac00cd commit 54bc252

1 file changed

Lines changed: 59 additions & 0 deletions

File tree

README.md

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -408,6 +408,65 @@ count individually towards rate limiting.
408408
See ``facebook_business.exceptions`` for a list of exceptions which may be thrown by
409409
the SDK.
410410

411+
## Conversions API
412+
413+
The Business SDK includes a server-side client for the [Conversions API](https://developers.facebook.com/docs/marketing-api/conversions-api), used to send web, app, and offline events to Meta directly from your server.
414+
415+
```python
416+
import time
417+
from facebook_business.adobjects.serverside.action_source import ActionSource
418+
from facebook_business.adobjects.serverside.custom_data import CustomData
419+
from facebook_business.adobjects.serverside.event import Event
420+
from facebook_business.adobjects.serverside.event_request import EventRequest
421+
from facebook_business.adobjects.serverside.user_data import UserData
422+
from facebook_business.api import FacebookAdsApi
423+
424+
FacebookAdsApi.init(access_token='<ACCESS_TOKEN>')
425+
426+
user_data = UserData(
427+
email='joe@eg.com',
428+
client_ip_address=request.META.get('REMOTE_ADDR'),
429+
client_user_agent=request.headers['User-Agent'],
430+
)
431+
custom_data = CustomData(currency='usd', value=123.45)
432+
event = Event(
433+
event_name='Purchase',
434+
event_time=int(time.time()),
435+
user_data=user_data,
436+
custom_data=custom_data,
437+
event_source_url='http://jaspers-market.com/product/123',
438+
action_source=ActionSource.WEBSITE,
439+
)
440+
response = EventRequest(pixel_id='<PIXEL_ID>', events=[event]).execute()
441+
print(response)
442+
```
443+
444+
For advanced features — asynchronous requests, concurrent batching, and a custom HTTP service — see [Meta Business SDK Features for Conversions API](https://developers.facebook.com/documentation/ads-commerce/conversions-api/guides/business-sdk-features/).
445+
446+
### Conversions API Parameter Builder integration
447+
448+
The SDK bundles the [Conversions API Parameter Builder](https://github.com/facebook/capi-param-builder) ([Python README](https://github.com/facebook/capi-param-builder/blob/main/python/README.md)) so it can auto-fill key event parameters straight from the incoming HTTP request. Call `set_request_context()` on an event and pass the incoming request — see [Framework support](https://github.com/facebook/capi-param-builder/blob/main/python/README.md#framework-support) for exactly what to pass for your framework (e.g. a WSGI request such as Django `request` / Flask `request`, an ASGI scope, or a raw environ dict). At send time the SDK runs the Parameter Builder and fills in any of these fields you left empty:
449+
450+
- `user_data.fbc`, `user_data.fbp`
451+
- `event_source_url`, `referrer_url`
452+
453+
```python
454+
from facebook_business.adobjects.serverside.preference import Preference
455+
456+
event = Event(
457+
event_name='Purchase',
458+
event_time=int(time.time()),
459+
user_data=UserData(email='joe@eg.com'),
460+
action_source=ActionSource.WEBSITE,
461+
).set_request_context(request)
462+
463+
# Optional: gate which fields may be auto-filled (all default True).
464+
# Order: fbc, fbp, client_ip_address, referrer_url, event_source_url.
465+
# .set_request_context(request, Preference(True, True, True, True, False))
466+
```
467+
468+
Auto-fill is **gated** by the optional `Preference` allowlist, **non-destructive** (a value you set yourself is never overwritten), and **order-independent**. Note that in Python, `client_ip_address` is not auto-derived yet — keep setting it (and `client_user_agent`) yourself.
469+
411470
## Tests
412471

413472
### Unit tests

0 commit comments

Comments
 (0)