Sending Engagements from your server
Your servers can log records using Promoted's Metrics API. The Metrics API accepts LogRequest proto messages as JSON HTTP requests.
This is useful when:
- Logging purchase actions securely from your server.
- If you are trying to reuse existing log streams. Promoted recommends using our client-side SDKs directly (includes better utilities and less likely to have errors).
Example: purchase records
Here's an example for logging a purchase to Promoted. The LogRequest message supports batch logging records.
# Some fields like `timing`, `insertionId`, `impressionId`, `properties` and `cart` are optional on Action records.
echo '{
"userInfo": {
"anonUserId": "0ea9657c-bd64-4709-9cc0-fbbcdd8d9f43",
"userId": "user1"
},
"action": [
{
"actionId": "b59b77c7-a55a-4f01-91b5-58a3d4e36876",
"timing": {
"clientLogTimestamp": 1641038400000
},
"actionType": "PURCHASE",
"insertionId": "b59b77c7-a55a-4f01-91b5-58a3d4e36876",
"contentId": "123",
"impressionId": "cb97da40-1c56-45fc-b8c5-c525c384ae48",
"properties": {
"struct": {
"customKey1": "customValue",
"customKey2": 3
}
},
"cart": {
"contents": [
{
"contentId": "abc",
"quantity": 1,
"pricePerUnit": {
"currencyCode": "USD",
"amountMicros": 10000000
}
}
]
}
}
]
}' > /tmp/action.json
curl -H "Content-Type: application/json" \
-H "x-api-key: yourapikey" --data "@/tmp/action.json" http://www.promoted.ai/log
In this example:
anonUserId
is the anonymous user ID that matches the other log records. Usually this needs to be plumbed through more code paths.amountMicros
is the currency amount (e.g.$
s) multiplied by 1 million. This let's us keep money values as longs.
Custom properties
Custom properties can be added using properties.struct
. This is especially beneficial for complex actions, such as order mutations. Promoted can subsequently extract and utilize these custom properties. Please ensure you only add non-sensitive fields. If you want to include sensitive fields or are unsure about what fields to add, please reach out to Promoted.
// Switching to Typescript to support inline comments.
const logRequest = {
userInfo: {
anonUserId: "0ea9657c-bd64-4709-9cc0-fbbcdd8d9f43",
userId: "user1"
},
action: [
{
actionId: "b59b77c7-a55a-4f01-91b5-58a3d4e36876",
actionType: "CUSTOM_ACTION_TYPE",
customActionType: "MODIFY_ORDER",
contentId: "123",
properties: {
struct: {
// Let Promoted know if you have sensitive fields custom properties.
orderId: "abc",
// Can log the delta to an order.
orderDelta: [
{
"contentId": "abc",
"quantity": -2,
"pricePerUnit": {
"currencyCode": "USD",
"amountMicros": 10000000
}
}
],
// Can also log the current order state.
currentOrder: [
{
"contentId": "abc",
"quantity": 1,
"pricePerUnit": {
"currencyCode": "USD",
"amountMicros": 10000000
}
},
{
"contentId": "def",
"quantity": 2,
"pricePerUnit": {
"currencyCode": "USD",
"amountMicros": 10000000
}
}
]
}
}
}
]
};
Example: impression record
This might happen if you have your own impression records and want to log them from your server instead of using Promoted's Snowplow-compatible path.
# insertionId is optional. It improves joining.
echo '{
"userInfo": {
"anonUserId": "0ea9657c-bd64-4709-9cc0-fbbcdd8d9f43",
"userId": "user1"
},
"impression": [
{
"impressionId": "cb97da40-1c56-45fc-b8c5-c525c384ae48",
"timing": {
"clientLogTimestamp": 1641038400000
},
"insertionId": "b59b77c7-a55a-4f01-91b5-58a3d4e36876",
"contentId": "123"
}
]
}' > /tmp/impression.json
curl -H "Content-Type: application/json" \
-H "x-api-key: yourapikey" --data "@/tmp/impression.json" http://www.promoted.ai/log
Updated 28 days ago