At a glance: Use the Web Server-to-Server (Web-S2S) events API to report events and conversions to PBA that aren't reported by the Web SDK.
Web Server-to-server events API for PBA
The Web-S2S API for People-Based Attribution complements the Web SDK allowing marketers to report events occurring on their websites but outside the scope of the Web SDK. For example, a visitor to the website (a web user), triggers an online payment event, processed by backend systems. After processing, the backend, using the S2S API, reports the event to AppsFlyer.
Events sent by the S2S API:
- are recorded similarly to events reported by the Web SDK
- are included in PBA dashboards if set as conversion events
- populate PBA raw data with event_source field set to web S2S
API use instructions
Create your API call using the sections that follow.
No. | Item | Remarks |
---|---|---|
1 | Unique user ID |
|
2 | Timestamp |
|
3 | Revenue and currency | You must populate eventRevenueCurrency and eventRevenue even if they are contained in the eventValue. Do so because we use them in our dashboards. |
API basics
API implementation requires the following credentials available in the dashboard:
- Bundle ID (aka brand bundle ID)
- Web Dev key
To get the credentials:
- In AppsFlyer, from the top menu, select My Apps > View brand bundles.
The list of bundles display. - Copy and record the appropriate:
- Brand bundle ID
- Web dev key
Web S2S API basics
Path |
|
HTTP method | POST |
Accepted content type |
application/json |
JSON payload limitation |
JSON payload size: maximum 1KB |
Rate limitation |
POST limitation volume: 60,000 POSTs per minute. To increase the limit, contact your CSM. |
TLS |
|
setCuId method
Method name |
setCuId |
Use case |
On associating a CUID with a visitor to your website. For example, any time you match the web |
Method path |
|
Payload |
The JSON payload consists of the parameters listed here. All parameters are mandatory. |
Curl example setCuId
curl --location --request POST 'https://webs2s.appsflyer.com/v1/bundleId/setcuid' \
--header 'Accept-Encoding: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"customerUserId": "1234567890abcdef",
"afUserId":"9999999-f848-4963-a091-568f0bf9a361",
"webDevKey" : "99999999-9999-9999-9999-999999999999"}
Event method
Method name |
event |
Use case | Send |
Method Path |
|
Detailed information | Event method details section of this article contains payload details, Curl example, Python example and testing suggestions. |
Event method details
Payload parameters
Payload parameters are divided into user identifiers and event parameters.
- User ID: You must send at least one user ID parameter.
- Event: Send the mandatory parameters and optional parameters as needed.
User identifier parameters (send at least one parameter)
User ID Parameter | Description |
---|---|
customerUserId |
Customer user ID (CUID) is a unique identifier set by you.
|
afUserId |
The unique user ID assigned by the Web SDK to every user that visits your website. You will need to pass the cookie value to your backend servers.
|
Event parameters
Parameter Name | Mandatory | Description |
---|---|---|
webDevKey |
Yes |
Populate using the web dev key available on the Dashboard.
|
eventType | Yes |
Event attribute identifier for internal use by AppsFlyer. Always set to EVENT.
|
eventName | Yes |
|
timestamp | No |
Time the event occurred in milliseconds. Send as a Unix timestamp having 13 digits.
|
eventValue | No |
Map of event parameters describing the event. Use this parameter to send rich in-app events like product SKU, line item price.
|
eventRevenueCurrency | No |
Currency code of a revenue event, being a three-character ISO 4217 currency code.
|
eventRevenue | No |
Revenue (monetary value) assigned to an event. Note! If revenue is reported in eventValue, report it also in eventRevenue and populate eventRevenueCurrency.
|
No | This parameter is deprecated and will be removed from the system at a future date. Use eventValue instead. | |
No |
This parameter is deprecated and will be removed from the system at a future date. Use eventValue instead. |
|
referrer | No |
HTTP referrer
|
userAgent | No |
User-agent request sent by the browser to the server.
|
ip | No |
User IP address
|
Curl example
curl --location --request POST 'https://webs2s.appsflyer.com/v1/bundleId/event' \
--header 'Accept-Encoding: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"customerUserId": "1234567890abcdef",
"afUserId":"9999999-f848-4963-a091-568f0bf9a361",
"webDevKey" : "99999999-9999-9999-9999-999999999999",
"ip" : "192.0.2.1",
"eventType":"EVENT",
"timestamp" : 1234567890123,
"eventName":"my_web_event",
"eventRevenueCurrency" : "EUR",
"eventRevenue" : 1234.56,
"eventValue": {
"purchase":{
"shoes": "color",
"quantity" : "3",
"Revenue" : "1234.56",
"Currency" : "ZAR"
}
}
}'
Python example
''' using the requests python package, install using pip install requests '''
import requests
url = "https://webs2s.appsflyer.com/v1/bundleId/event"
payload = {
"customerUserId": "1234567890abcdef",
"afUserId": "9999999-f848-4963-a091-568f0bf9a361",
"webDevKey": "99999999-9999-9999-9999-999999999999",
"ip": "192.0.2.1",
"eventType": "EVENT",
"timestamp": 1234567890123,
"eventName": "my_web_event",
"eventRevenenuCurrency": "EUR",
"eventRevenue": 1234.56,
"eventValue":
{
"purchase":
{
"shoes": "color",
"quantity": "3",
"Revenue": "1234.56",
"Currency": "ZAR"
}
}
}
headers = {
'Accept-Encoding': 'application/json',
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, json=payload)
print(response.text.encode('utf8'))
Testing
For testing purposes, send several events as follows:
- Send an event.
- Ensure that you get a 200 OK return code. If not, take corrective action using the return codes and error messages.
- Wait for several hours after midnight UTC to see the reported event in PBA raw data. You must wait because PBA data is processed once a day.
Additional information
Getting the Web Dev Key
Extracting the Web SDK afUserID
- The
afUserId
, is a unique identifier, set by the Web SDK when a user first visits your site. - If you need
afUserId
use one of the methods that follow.
Get afUserId from the HTTP cookie header
- The
afUserId
is sent by the visitors browser on calls to your site. - Extract it from the HTTP cookie header if needed.
Viewing afUserId in the visitor's browser
- View the
afUserId
in the visitor's browser, for troubleshooting and debugging purposes. - For it to be available, the visitor needs to have first visited a page having the Web SDK at least once.
- The cookie containing
afUserId
is a first-party cookie in relation to your domain. - The procedure that follows was prepared using Chrome 81. There may be some differences between various browsers and operating systems.
To get the afUserId from the visitor's browser:
- In your browser, go to your website.
-
Right-click, select Inspect
The browser's inspect element window opens. - Go to the (A) Application tab.
- In the side menu, (B) expand Cookies.
- Select your website. If it does not display, refresh the browser.
- In the (C) filter field, enter
afUserId
The value of afUserID displays.
Response codes
Response code | Message | How to Handle |
---|---|---|
200 | OK | |
404 | Not found |
|
400 | Bad request |
|
Troubleshooting
- Symptom: HTTP return codes do not return
Solution: Allowlist AppsFlyer servers.
Release notes
Date | Endpoint Version* | Notes |
---|---|---|
2020-05-12 | 1 | Initial release |
2020-05-24 | 1 | |
* Version number relates to the endpoint version number. https://webs2s.appsflyer.com/v1/method
|