Skip to content

Commit 2130853

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 dc91b33 commit 2130853

1 file changed

Lines changed: 57 additions & 0 deletions

File tree

README.md

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -348,6 +348,63 @@ Here are some hints on troubleshooting:
348348
* For temporary server issue, typically retry should work after a few seconds.
349349
* If server persistently responds with "Unknown error," then it is potentially server bug.
350350

351+
## Conversions API
352+
353+
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.
354+
355+
```java
356+
import com.facebook.ads.sdk.APIContext;
357+
import com.facebook.ads.sdk.serverside.*;
358+
359+
APIContext context = new APIContext("<ACCESS_TOKEN>");
360+
361+
UserData userData = new UserData()
362+
.email("joe@eg.com")
363+
.clientIpAddress(request.getRemoteAddr())
364+
.clientUserAgent(request.getHeader("User-Agent"));
365+
366+
CustomData customData = new CustomData()
367+
.currency("usd")
368+
.value(123.45F);
369+
370+
Event event = new Event()
371+
.eventName("Purchase")
372+
.eventTime(System.currentTimeMillis() / 1000L)
373+
.userData(userData)
374+
.customData(customData)
375+
.eventSourceUrl("http://jaspers-market.com/product/123")
376+
.actionSource(ActionSource.website);
377+
378+
EventRequest eventRequest = new EventRequest("<PIXEL_ID>", context);
379+
eventRequest.addDataItem(event);
380+
EventResponse response = eventRequest.execute();
381+
System.out.println(response);
382+
```
383+
384+
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/).
385+
386+
### Conversions API Parameter Builder integration
387+
388+
The SDK bundles the [Conversions API Parameter Builder](https://github.com/facebook/capi-param-builder) ([Java README](https://github.com/facebook/capi-param-builder/blob/main/java/README.md)) so it can auto-fill key event parameters straight from the incoming HTTP request. Call `setRequestContext()` on an event and pass the incoming request — see [Framework support](https://github.com/facebook/capi-param-builder/blob/main/java/README.md#framework-support) for exactly what to pass for your framework (e.g. a `javax`/`jakarta` `HttpServletRequest`, a Spring WebFlux `ServerHttpRequest`, or a CGI/WSGI-style `Map`). At send time the SDK runs the Parameter Builder and fills in any of these fields you left empty:
389+
390+
- `user_data.fbc`, `user_data.fbp`
391+
- `event_source_url`, `referrer_url`
392+
393+
```java
394+
Event event = new Event()
395+
.eventName("Purchase")
396+
.eventTime(System.currentTimeMillis() / 1000L)
397+
.userData(new UserData().email("joe@eg.com"))
398+
.actionSource(ActionSource.website)
399+
.setRequestContext(request);
400+
401+
// Optional: gate which fields may be auto-filled (all default true).
402+
// Order: fbc, fbp, client_ip_address, referrer_url, event_source_url.
403+
// .setRequestContext(request, new Preference(true, true, true, true, false));
404+
```
405+
406+
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 Java, `client_ip_address` is not auto-derived yet — keep setting it (and `client_user_agent`) yourself.
407+
351408
## SDK Codegen
352409
Our SDK is autogenerated from [SDK Codegen](https://github.com/facebook/facebook-business-sdk-codegen). If you want to learn more about how our SDK code is generated, please check this repository.
353410

0 commit comments

Comments
 (0)