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