Facebook Marketing Responder user guide - snowplow-archive/sauna GitHub Wiki

HOME > GUIDE FOR ANALYSTS > RESPONDERS > Facebook Marketing Responder user guide

This responder has not yet been implemented.

See also: Facebook Marketing Responder setup guide

• 1. Overview
• 2. Responder actions
  • 2.1 Add users to custom audience (real-time)
    • 2.1.1 Overview
    • 2.1.2 Command format
    • 2.1.3 Example command
    • 2.1.4 Response algorithm
    • 2.1.5 Usage examples
      • 2.1.5.1 Kinesis stream

This responder lets you interact with the Facebook Marketing API, so you can market to your customers from inside Facebook.

Currently this responder only supports one action:

This responder command lets you add one or more users to an existing Facebook custom audience. Under the hood, this command is an authenticated call to the [Users endpoint][audience-api-users] within the [Audiences API][audience-api].

Like all real-time responder actions, this action is triggered by a well-structured JSON command being received by a compatible observer.

The command must be configured using a self-describing JSON Schema which validates against this schema:

iglu:com.facebook.marketing.audiences.sauna.commands/add_users/jsonschema/1-0-0

A simple add users command will look as follows:

{
  "schema": "iglu:com.facebook.marketing.audiences.sauna.commands/add_users/jsonschema/1-0-0",

  "data": {
    "customAudienceId": "3434",
    "appIds": ["123", "456"],
    "users": {
      "schema": [
        "EMAIL",
        "MADID",
        "APPUID"
      ],
      "data": [
        [ 
          "b36a83701f1c3191e19722d6f90274bc1b5501fe69ebf33313e440fe4b0fe210", 
          "1234567890", 
          "6032d997-3ab0-4de0-aa16-8af0e5b482fb" 
        ], 
        [ 
          "2b3b2b9ce842ab8b6a6c614cb1f9604bb8a0d502d1af49c526b72b10894e95b5", 
          "", 
          "B67385F8-9A82-4670-8C0A-6F9EA7513F5F" 
        ], 
        [ 
          "898628e28890f937bdf009391def42879c401a4bcf1b5fd24e738d9f5da8cbbb", 
          "9876543210", 
          "" 
        ] 
      ],
      "preHashed": true
    }
  }
}

Where:

• customAudience identifies the pre-existing custom audience to add users to
• appIds is an array of Facebook Apps that the specified APPUID will apply to. Leave it as an empty array if you are not using APPUID
• users.schema is an array specifying the types of the user-identifiable datapoints provided in the following data section for each user
• users.data is an array of arrays. The outer array has maximum length of 10,000 and will contain an entry for each user to add to the custom audience. Each user entry is itself an array, containing the user-identifiable datapoints specified in the users.schema. The order of the data points must correspond to the order in the users.schema.
• users.preHashed specifies whether or not the users.data has already been hashed. If not, Sauna will automatically hash the data

As with all RT responders, Sauna will take each command and:

1. Validate it as a valid Facebook Marketing custom audiences add_users command
2. If it is not valid, this will be reported to any configured Sauna loggers
3. If it is valid, Sauna will attempt to send the command to the [Users endpoint][audience-api-users] within the [Audiences API][audience-api]
4. If the API reports success (200), this will be reported to any configured Sauna loggers
5. If the API reports failure (400/403/etc), this will be reported to any configured Sauna loggers but no retry will be attempted

In the case of failure, we do not attempt retry, even in the case of us temporarily exceeding API rate limits, because this could block other non-Facebook-related commands in the observed stream from executing.

Assuming that the Amazon Kinesis Observer receives the following command:

{
  "schema": "iglu:com.snowplowanalytics.sauna.commands/command/jsonschema/1-0-0",

  "data": {
    "envelope": {
      "schema": "iglu:com.snowplowanalytics.sauna.commands/envelope/jsonschema/1-0-0",
      "data": {
        "commandId": "9dadfc92-9311-43c7-9cee-61ab590a6e81",
        "whenCreated": "2017-01-02T19:14:42Z",
        "execution": {
          "semantics": "AT_LEAST_ONCE",
          "timeToLive": 1200000
        },
        "tags": {}
      }
    },
    "command": {
      "schema": "iglu:com.facebook.marketing.audiences.sauna.commands/add_users/jsonschema/1-0-0",

      "data": {
        "customAudienceId": "3434",
        "appIds": ["123", "456"],
        "users": {
          "schema": [
            "EMAIL",
            "MADID",
            "APPUID"
          ],
          "data": [
            [ 
              "b36a83701f1c3191e19722d6f90274bc1b5501fe69ebf33313e440fe4b0fe210", 
              "1234567890", 
              "6032d997-3ab0-4de0-aa16-8af0e5b482fb" 
            ], 
            [ 
              "2b3b2b9ce842ab8b6a6c614cb1f9604bb8a0d502d1af49c526b72b10894e95b5", 
              "", 
              "B67385F8-9A82-4670-8C0A-6F9EA7513F5F" 
            ], 
            [ 
              "898628e28890f937bdf009391def42879c401a4bcf1b5fd24e738d9f5da8cbbb", 
              "9876543210", 
              "" 
            ] 
          ],
          "preHashed": true
        }
      }
    }
  }
}

And assuming that the current time is within 20 minutes (1,200,000 ms) of 2017-01-02T19:14:42Z, then:

• Sauna will add three users to the Facebook Marketing custom audience 3434 application. The specified APPUID will be tied to the Facebook Apps 123 and 456
• Whether or not the event was successfully send will be reported to any configured Sauna loggers.