Skip to content

Commit 8dd0ede

Browse files
Jiaming Youmeta-codesync[bot]
Jiaming You
authored and
meta-codesync[bot]
committed
recommend processRequestFromContext in READMEs
Summary: Update the SDK READMEs (nodejs, python, ruby, php, java) so the "API usage" section leads with the context-based entry point instead of the legacy positional one. - The "process request" step now recommends `processRequestFromContext` / `process_request_from_context`, which auto-extracts host / cookies / query / referer from the framework request object and also constructs `event_source_url`. It returns the same cookies-to-set list as the old API. - The legacy `processRequest` / `process_request` form is now shown under a **Deprecated** note (it does not construct `event_source_url`), with its full example retained for reference. - Each step links to the existing `## Framework support` section for what request object to pass per framework (and the adjustments needed for unsupported frameworks). - Added `event_source_url` / `referrer_url` getters to the API-usage send payload, and added `referrer_url` to the `## URL support` payload example (it previously only showed `event_source_url`). - Fixed long-standing typos in the example payload blocks while touching them: malformed `event_name` key (missing closing quote), `event_tme` -> `event_time`, and `//` -> `#` comment markers in the Python and Ruby pseudo-payloads. Per-language method and getter names follow each SDK convention (camelCase for nodejs/php/java, snake_case for python/ruby) and were verified against the SDK source. Docs-only change; no code or runtime behavior is affected. ___ Differential Revision: D107900758 fbshipit-source-id: 240c5cc67f6a7aefedfbf26540a0a19fc5ae13a3
1 parent cae6fec commit 8dd0ede

5 files changed

Lines changed: 118 additions & 49 deletions

File tree

‎java/README.md‎

Lines changed: 27 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -120,10 +120,23 @@ ParamBuilder paramBuilder = new ParamBuilder(Arrays.asList('example.com', 'yourD
120120
// ParamBuilder paramBuilder = new ParamBuilder();
121121
```
122122

123-
4. Call `processRequest` to process the fbc, fbp
123+
4. [Recommended] Call `processRequestFromContext` to process fbc, fbp,
124+
eventSourceUrl and referrerUrl. Pass your framework's request object (e.g. a
125+
Servlet `HttpServletRequest`, Spring WebFlux `ServerHttpRequest`, or a raw
126+
environ-style `Map`) directly — the SDK extracts host / cookies / query /
127+
referer (and the request URI for `eventSourceUrl`) for you, and returns the
128+
recommended cookies to set. See the [Framework support](#framework-support)
129+
section for exactly what to pass for your framework.
124130

125131
```
126-
// Option 1: recommended - with referer url
132+
List<CookieSetting> updatedCookieList = paramBuilder.processRequestFromContext(request);
133+
```
134+
135+
**Deprecated:** `processRequest` is still supported but deprecated. It does not
136+
construct `eventSourceUrl`. Prefer `processRequestFromContext` above.
137+
138+
```
139+
// Option 1: with referer url
127140
List<CookieSetting> updatedCookieList =
128141
paramBuilder.processRequest(
129142
request.getHeader("host"),
@@ -144,12 +157,13 @@ List<CookieSetting> updatedCookieList =
144157
save cookie API may vary. Feel free to choose the best fit for your use case.
145158
Below uses the example from the demo application.
146159

147-
Option 1: Get the updatedCookieList list from `processRequest` in step 4 above.
160+
Option 1: Get the `updatedCookieList` list from `processRequestFromContext` in
161+
step 4 above.
148162

149163
```
150-
// Call the processRequest as show in step 4 above.
164+
// Call the processRequestFromContext as show in step 4 above.
151165
List<CookieSetting> updatedCookieList =
152-
paramBuilder.processRequest(..);
166+
paramBuilder.processRequestFromContext(request);
153167
154168
// Save cookies for the list of updated cookie list
155169
for (CookieSetting updatedCookie : updatedCookieList) {
@@ -164,7 +178,7 @@ Option 2: use `getCookiesToSet` API.
164178

165179
```
166180
// Still need process the request.
167-
paramBuilder.processRequest(..);
181+
paramBuilder.processRequestFromContext(request);
168182
169183
// Save cookies for the list of updated cookie list
170184
for (CookieSetting updatedCookie : paramBuilder.getCookiesToSet()) {
@@ -197,11 +211,13 @@ String referrerUrl = paramBuilder.getReferrerUrl();
197211

198212
```
199213
data=[
200-
'event_name: '...',
201-
'event_tme': <your_time>,
214+
'event_name': '...',
215+
'event_time': <your_time>,
216+
'event_source_url': eventSourceUrl, // The value provided in step 6
217+
'referrer_url': referrerUrl, // The value provided in step 6
202218
'user_data': {
203-
'fbc': fbc, // The value provided in step 5
204-
'fbp': fbp, // The value provided in step 5
219+
'fbc': fbc, // The value provided in step 6
220+
'fbp': fbp, // The value provided in step 6
205221
...
206222
}
207223
...
@@ -265,6 +281,7 @@ Map<String, Object> data = new HashMap<>();
265281
data.put("event_name", "...");
266282
data.put("event_time", System.currentTimeMillis() / 1000);
267283
data.put("event_source_url", paramBuilder.getEventSourceUrl());
284+
data.put("referrer_url", paramBuilder.getReferrerUrl());
268285

269286
Map<String, Object> userData = new HashMap<>();
270287
userData.put("fbc", paramBuilder.getFbc());

‎nodejs/README.md‎

Lines changed: 20 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -94,29 +94,29 @@ const builder = new ParamBuilder(etldPlus1Resolver);
9494
const builder = new ParamBuilder();
9595
```
9696

97-
3. Call `processRequest` to process the fbc, fbp and fbi(client_ip_address).
97+
3. [Recommended] Call `processRequestFromContext` to process fbc, fbp,
98+
client_ip_address, event_source_url and referrer_url. Pass your framework's
99+
request object directly — the SDK extracts host / cookies / query / referer
100+
(and the request URL for `event_source_url`) for you, and returns the
101+
recommended list of cookies to set. See the
102+
[Framework support](#framework-support) section for exactly what to pass for
103+
your framework.
98104

99105
```
100-
builder.processRequest(
101-
req.headers.host, // host full URL.
102-
params, // query params
103-
requestCookies, // current cookie
104-
req.headers.referer // optional, help enhance the accuracy
105-
req.headers['x-forwarded-for'] ?? null, // optional, help to select the best client_ip_address
106-
req.socket.remoteAddress ?? null // optional, help to select the best client_ip_address
107-
);
108-
109-
110-
or
106+
const cookiesToSet = builder.processRequestFromContext(req);
107+
```
111108

109+
**Deprecated:** `processRequest` is still supported but deprecated. It does not
110+
construct `eventSourceUrl`. Prefer `processRequestFromContext` above.
112111

112+
```
113113
const cookiesToSet = builder.processRequest(
114114
req.headers.host, // host
115115
params, // query params
116116
requestCookies, // current cookie
117117
req.headers.referer, // optional, help enhance the accuracy
118-
req.headers['x-forwarded-for'] ?? null, // optional, help to select the best client_ip_address
119-
req.socket.remoteAddress ?? null // optional, help to select the best client_ip_address
118+
req.headers['x-forwarded-for'] ?? null, // optional, help select the best client_ip_address
119+
req.socket.remoteAddress ?? null // optional, help select the best client_ip_address
120120
);
121121
```
122122

@@ -128,9 +128,9 @@ const cookiesToSet = builder.processRequest(
128128
Recommended: get the list of `cookiesToSet` from API call in step 3.
129129

130130
```
131-
// Call processRequest in above step 3.
131+
// Call processRequestFromContext in above step 3.
132132
// The returned cookiesToSet is the recommended list of cookies to be saved.
133-
const cookiesToSet = builder.processRequest(...);
133+
const cookiesToSet = builder.processRequestFromContext(req);
134134
for (const cookie of cookiesToSet) {
135135
responseCookies.push(cookie.name + '=' + cookie.value + '; Max-Age=' + cookie.maxAge + '; Domain=' + cookie.domain + '; Path=/');
136136
}
@@ -202,8 +202,10 @@ API is to get normalized and hashed (sha256) PII from input piiValue, supported
202202

203203
```
204204
data=[
205-
'event_name: '...',
205+
'event_name': '...',
206206
'event_time': <your_time>,
207+
'event_source_url': eventSourceUrl, // The value provided in step 5
208+
'referrer_url': referrerUrl, // The value provided in step 5
207209
'user_data': {
208210
'fbc': fbc, // The value provided in step 5
209211
'fbp': fbp, // The value provided in step 5
@@ -276,6 +278,7 @@ const data = {
276278
event_name: '...',
277279
event_time: Math.floor(Date.now() / 1000),
278280
event_source_url: builder.getEventSourceUrl(),
281+
referrer_url: builder.getReferrerUrl(),
279282
user_data: {
280283
fbc: builder.getFbc(),
281284
fbp: builder.getFbp(),

‎php/README.md‎

Lines changed: 19 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -113,7 +113,20 @@ example.demo.com. This option may be less accurate.
113113
$param_builder = new FacebookAds\ParamBuilder();
114114
```
115115

116-
3. Call `processRequest` to process fbc, fbp and fbi(client_ip_address).
116+
3. [Recommended] Call `processRequestFromContext` to process fbc, fbp,
117+
client_ip_address, event_source_url and referrer_url. Pass your framework's
118+
request context (or `null` to read from the `$_SERVER` / `$_COOKIE` / `$_GET`
119+
superglobals) — the SDK extracts host / cookies / query / referer (and the
120+
request URI for `event_source_url`) for you, and returns the recommended
121+
cookies to set. See the [Framework support](#framework-support) section for
122+
exactly what to pass for your framework.
123+
124+
```
125+
$cookie_to_set = $param_builder->processRequestFromContext(); // reads from $_SERVER
126+
```
127+
128+
**Deprecated:** `processRequest` is still supported but deprecated. It does not
129+
construct `event_source_url`. Prefer `processRequestFromContext` above.
117130

118131
```
119132
$param_builder->processRequest(
@@ -134,7 +147,7 @@ $param_builder->processRequest(
134147
Recommended: get `$cookie_to_set` from API call in step 3.
135148

136149
```
137-
$cookie_to_set = $param_builder->processRequest(...)
150+
$cookie_to_set = $param_builder->processRequestFromContext();
138151
```
139152

140153
Optional: getCookiesToSet API
@@ -212,8 +225,10 @@ API is to get normalized and hashed (sha256) PII from input piiValue, supported
212225

213226
```
214227
data=[
215-
'event_name: '...',
228+
'event_name': '...',
216229
'event_time': <your_time>,
230+
'event_source_url': $event_source_url, // The value provided in step 5
231+
'referrer_url': $referrer_url, // The value provided in step 5
217232
'user_data': {
218233
'fbc': $fbc, // The value provided in step 5
219234
'fbp': $fbp, // The value provided in step 5
@@ -288,6 +303,7 @@ $data = [
288303
'event_name' => '...',
289304
'event_time' => time(),
290305
'event_source_url' => $param_builder->getEventSourceUrl(),
306+
'referrer_url' => $param_builder->getReferrerUrl(),
291307
'user_data' => [
292308
'fbc' => $param_builder->getFbc(),
293309
'fbp' => $param_builder->getFbp(),

‎python/README.md‎

Lines changed: 26 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -84,7 +84,19 @@ down from your input URL. This may miss some accuracy.
8484
paramBuilder = ParamBuilder() # Not recommended.
8585
```
8686

87-
4. Call `process_request` function to process fbc and fbp
87+
4. [Recommended] Call `process_request_from_context` to process fbc, fbp,
88+
event_source_url and referrer_url. Pass your framework's request object (or
89+
WSGI/ASGI environ) directly — the SDK extracts host / cookies / query /
90+
referer (and the request URL for `event_source_url`) for you, and returns the
91+
recommended cookies to set. See the [Framework support](#framework-support)
92+
section for exactly what to pass for your framework.
93+
94+
```
95+
updated_cookies = paramBuilder.process_request_from_context(request)
96+
```
97+
98+
**Deprecated:** `process_request` is still supported but deprecated. It does not
99+
construct `event_source_url`. Prefer `process_request_from_context` above.
88100

89101
```
90102
updated_cookies = paramBuilder.process_request(
@@ -99,11 +111,12 @@ updated_cookies = paramBuilder.process_request(
99111
the save cookie API may vary. Feel free to choose the best fit for your use
100112
case. Below uses the example from demo application.
101113

102-
Option 1: Get the recommended saved cookie from step 4 `process_request` above.
114+
Option 1: Get the recommended saved cookie from step 4
115+
`process_request_from_context` above.
103116

104117
```
105-
// Get the recommended saved cookie from step 4 API
106-
updated_cookies = paramBuilder.process_request(...)
118+
# Get the recommended saved cookie from step 4 API
119+
updated_cookies = paramBuilder.process_request_from_context(request)
107120
108121
for cookie in updated_cookies:
109122
self.send_header( "Set-Cookie",
@@ -114,8 +127,8 @@ Option 2: Get the recommended saved cookie from
114127
`paramBuilder.get_cookies_to_set()`
115128

116129
```
117-
# process_request should be always called
118-
paramBuilder.process_request(...)
130+
# process_request_from_context should be always called
131+
paramBuilder.process_request_from_context(request)
119132
120133
for cookie in paramBuilder.get_cookies_to_set():
121134
self.send_header( "Set-Cookie",
@@ -144,11 +157,13 @@ referrer_url = paramBuilder.get_referrer_url()
144157

145158
```
146159
data=[
147-
'event_name: '...',
148-
'event_tme': <your_time>,
160+
'event_name': '...',
161+
'event_time': <your_time>,
162+
'event_source_url': event_source_url, # The value provided in step 6
163+
'referrer_url': referrer_url, # The value provided in step 6
149164
'user_data': {
150-
'fbc': fbc, // The value provided in step 5
151-
'fbp': fbp, // The value provided in step 5
165+
'fbc': fbc, # The value provided in step 6
166+
'fbp': fbp, # The value provided in step 6
152167
...
153168
}
154169
...
@@ -223,6 +238,7 @@ data = {
223238
"event_name": "...",
224239
"event_time": int(time.time()),
225240
"event_source_url": paramBuilder.get_event_source_url(),
241+
"referrer_url": paramBuilder.get_referrer_url(),
226242
"user_data": {
227243
"fbc": paramBuilder.get_fbc(),
228244
"fbp": paramBuilder.get_fbp(),

‎ruby/README.md‎

Lines changed: 26 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -106,7 +106,21 @@ builder = ParamBuilder.new()
106106
107107
```
108108

109-
4. Call `process_request` function to process fbc and fbp
109+
4. [Recommended] Call `process_request_from_context` to process fbc, fbp,
110+
event_source_url and referrer_url. Pass your framework's request object (or
111+
Rack `env` hash) directly — the SDK extracts host / cookies / query / referer
112+
(and the request URL for `event_source_url`) for you, and returns the
113+
recommended cookies to set. See the [Framework support](#framework-support)
114+
section for exactly what to pass for your framework.
115+
116+
```
117+
118+
cookies_to_be_updated = builder.process_request_from_context(request)
119+
120+
```
121+
122+
**Deprecated:** `process_request` is still supported but deprecated. It does not
123+
construct `event_source_url`. Prefer `process_request_from_context` above.
110124

111125
```
112126
@@ -123,14 +137,14 @@ cookies_to_be_updated = builder.process_request(
123137
framework, the save cookie API may vary. Feel free to choose the best fit for
124138
your use case. Below uses the example from demo application.
125139

126-
Option 1: Save the `cookies_to_be_updated` cookies from `process_request` to
127-
your response.
140+
Option 1: Save the `cookies_to_be_updated` cookies from
141+
`process_request_from_context` to your response.
128142

129143
```
130144
131145
# Get the recoomended saved cookie from step 4 above
132146
133-
cookies_to_be_updated = builder.process_request(...)
147+
cookies_to_be_updated = builder.process_request_from_context(request)
134148
135149
for cookie in cookies_to_be_updated do response.set_cookie(
136150
cookie.name,
@@ -150,7 +164,7 @@ response.
150164
151165
# Get the recoomended saved cookie from step 4 above
152166
153-
builder.process_request(...)
167+
builder.process_request_from_context(request)
154168
155169
# `cookies_to_be_updated` from get_cookies_to_set()
156170
@@ -198,11 +212,13 @@ referrer_url = builder.get_referrer_url()
198212
```
199213
200214
data=[
201-
'event_name: '...',
202-
'event_tme': <your_time>,
215+
'event_name': '...',
216+
'event_time': <your_time>,
217+
'event_source_url': event_source_url, # The value provided in step 6
218+
'referrer_url': referrer_url, # The value provided in step 6
203219
'user_data': {
204-
'fbc': fbc, // The value provided in step 5
205-
'fbp': fbp, // The value provided in step 5 ...
220+
'fbc': fbc, # The value provided in step 6
221+
'fbp': fbp, # The value provided in step 6 ...
206222
}
207223
...
208224
]
@@ -262,6 +278,7 @@ data = {
262278
event_name: '...',
263279
event_time: Time.now.to_i,
264280
event_source_url: builder.get_event_source_url(),
281+
referrer_url: builder.get_referrer_url(),
265282
user_data: {
266283
fbc: builder.get_fbc(),
267284
fbp: builder.get_fbp(),

0 commit comments

Comments
 (0)