Send results to Facebook Ads

Facebook Ads appear in the news feed and in the right-side column on Facebook. Facebook Ads provides an API for integrating with third-party systems.

Note

This destination uses the Facebook Marketing API .

Changes to audiences are not immediately available in Facebook Ads. Allow for up to 24 hours after the point at which Amperity has finished sending audience updates for them to be available.

Important

Amperity requires access to Facebook Ads. This access may expire or be removed periodically, depending on how OAuth is managed at Facebook Ads. If Amperity is unable to send data to Facebook Ads ask your DataGrid Administrator to reauthorize access to Facebook Ads.

This topic describes the steps that are required to send customer data to Facebook Ads from Amperity:

  1. Build a query

  2. Add orchestration

  3. Run orchestration

Note

Facebook Ads must be enabled before you can configure an orchestration to send query results. Ask your DataGrid Operator or Amperity representative to enable Facebook Ads for your tenant.

Build query

You will need to build a query that shapes the data so that fields in the output are mapped to the Facebook Marketing API keys.

Data mapping for Facebook Ads is only required one time. You can do this in the following ways:

  1. Add a Facebook table to the customer 360 database that selects PII fields in the Customer360 table, and then outputs them to a table with columns that map to the Facebook Ads naming patterns.

  2. Add a SQL query that does the filtering within the query, and then outputs results that do not require a data template.

The correct approach here depends on the data and the desired use case (or cases) for downstream workflows.

Use a Facebook table

A Facebook table collects PII data from the Customer360 table, and then creates a table with columns that match the naming pattern for fields in the Facebook Marketing API. This approach allows the Visual Query Editor to use the Facebook table to filter by matching records. In the customer 360 database, add a SQL table with a SELECT statement similar to:

SELECT
  amperity_id
  ,LOWER(email) AS EMAIL
  ,CONCAT('+1','',REGEXP_REPLACE(Phone,'[$\D\s]','')) AS PHONE
  ,REGEXP_REPLACE(FirstName, '[^\w\s]', '') AS FN
  ,REGEXP_REPLACE(LastName, '[*@/.,-_]', '') AS LN
  ,REGEXP_EXTRACT(PostalCode,'^(\d{5})') AS ZIP
  ,LOWER(REPLACE(City, ' ', '')) AS CT
  ,UPPER(state) AS ST
  ,'US' AS COUNTRY
  ,birthdate AS BIRTH
  ,SUBSTR(LOWER(Gender),1,1) AS GEN
FROM customer360
WHERE DATE_DIFF('day', LastPurchase, Now()) = 1

and then run the customer 360 database to update that table. After the table has run, you can use a visual query to define a query that filters by matching records in the Facebook table. This will return any record in the Facebook table that matches the query and will return the results with all of the fields in the Facebook table.

For example, you could define a query that finds all transactions in the past week for all email addresses, and then match records against the Facebook table. The results will contain the columns in the Facebook table for all emails associated with a transaction in the past week.

Use a SQL query

A SQL query can output results that map to fields in the Facebook Marketing API. This process is similar to building a table, but instead of the output to a table, it is to a query. This approach does not require a data template, but may not be reusable for multiple downstream workflows.

Add a SQL table with a SELECT statement similar to:

SELECT
  amperity_id
  ,LOWER(email) AS EMAIL
  ,CONCAT('+1','',REGEXP_REPLACE(Phone,'[$\D\s]','')) AS PHONE
  ,REGEXP_REPLACE(FirstName, '[^\w\s]', '') AS FN
  ,REGEXP_REPLACE(LastName, '[*@/.,-_]', '') AS LN
  ,REGEXP_EXTRACT(PostalCode,'^(\d{5})') AS ZIP
  ,LOWER(REPLACE(City, ' ', '')) AS CT
  ,UPPER(State) AS ST
  ,'US' AS COUNTRY
  ,Birthdate AS BIRTH
  ,SUBSTR(LOWER(Gender),1,1) AS GEN
FROM customer360
WHERE DATE_DIFF('day', LastPurchase, Now()) = 1
LIMIT 2000

and then assign this query to a destination that sends results to Facebook Ads.

Add orchestration

An orchestration defines the relationship between query results and a destination, including the location to which those query results will be sent and the frequency at which the orchestration will be run.

To add an orchestration

  1. From the Destinations tab, click Add Orchestration. This opens the Add Orchestration dialog box.

  2. From the Object Type drop-down, select Query.

  3. From the Object drop-down, select the query for which results will be sent to Facebook Ads.

  4. From the Destination drop-down, select a destination that is configured for sending data to Facebook Ads.

  5. From the Data Template drop-down, select a data template.

  6. Verify all settings.

  7. Set the workflow to Manual. (You can change this to automatic later, after verifying the end-to-end workflow.)

  8. Click Save.

Run orchestration

Run the orchestration manually to validate that it works.

To add an orchestration

  1. From the Destinations tab, click Add Orchestration. This opens the Add Orchestration dialog box.

  2. From the Object Type drop-down, select Query.

  3. From the Object drop-down, select the query for which results will be sent to Facebook Ads.

  4. From the Destination drop-down, select a destination that is configured for sending data to Facebook Ads.

  5. From the Data Template drop-down, select a data template.

  6. Verify all settings.

  7. Set the workflow to Manual. (You can change this to automatic later, after verifying the end-to-end workflow.)

  8. Click Save.

Warning

If the Terms of Service (ToS) for Custom Audiences have not been accepted you will get a permissions error with a link to the ToS. Someone with access to the Facebook account will need to accept the ToS before Custom Audiences will be sent.

Facebook Marketing API keys

The following Amperity columns should be mapped to the corresponding Facebook Marketing API keys when they are present in query data:

Amperity Column

Facebook API Key

Description

Amperity ID

EXTERN_ID

This value is a unique ID used by the advertiser, such as a loyalty ID, a customer ID, an external cookie ID, or the Amperity ID.

For this key, the connector trims leading and trailing whitespace.

Tip

A query can alias the Amperity ID directly in a query: SELECT amperity_id AS EXTERN_ID from custom_table. This approach can be helpful for queries that are dedicated to returning data to be sent only to Facebook Ads.

Email Addresses

EMAIL

For this key, the connector:

  • Trims leading and trailing whitespace

  • Converts to lower-case

  • Hashes data as SHA-256

Phone Numbers

PHONE

Converts each phone number to E.164 format which represents a phone number as a number up to fifteen digits in length (without spaces) that starts with a + symbol. For example: +12061234567.

For this key, the connector:

  • Trims leading and trailing whitespace

  • Removes symbols, letters, and any leading zeros

  • Hashes data as SHA-256

Gender

GEN

For this key, the connector:

  • Trims leading and trailing whitespace

  • Converts to lower-case

  • Converts to m and f

  • Hashes data as SHA-256

Birth Date

BIRTH

The birth date in Amperity date format.

For this key, the connector splits this value into three fields: birth year (DOBY), birth month (DOBM), and birth day (DOBD).

Birth Year

DOBY

Warning

Do not pass this column. For this key, the connector will use birthdate to split out the value for DOBY with a format of YYYY and a range from 1900 to the current year.

Birth Month

DOBM

Warning

Do not pass this column. For this key, the connector will use birthdate to split out the value for DOBM with a format of 01 to 12.

Birth Day

DOBD

Warning

Do not pass this column. For this key, the connector will use birthdate to split out the value for DOBD with a format of 01 to 31.

Last Name

LN

This key supports special characters and non-Roman alphabet characters. For this key, the connector:

  • Trims leading and trailing whitespace

  • Converts to lower-case

  • Removes punctuation

  • Updates special characters to UTF-8 format

  • Hashes data as SHA-256

First Name

FN

This key supports special characters and non-Roman alphabet characters. For this key, the connector:

  • Trims leading and trailing whitespace

  • Converts to lower-case

  • Removes punctuation

  • Updates special characters to UTF-8 format

  • Hashes data as SHA-256

First Initial

FI

Warning

Do not pass this column. The connector will use the first character of the normalized first name.

US States

ST

A two-character ANSI abbreviation code for US states.

For this key, the connector:

  • Trims leading and trailing whitespace

  • Converts to lower-case

  • Normalizes states located outside of the United States

  • Removes punctuation, special characters, and whitespace

  • Hashes data as SHA-256

City

CT

For this key, the connector:

  • Trims leading and trailing whitespace

  • Converts to lower-case

  • Removes punctuation, special characters, and whitespace

  • Hashes data as SHA-256

Zip Code

ZIP

Use only the first five digits for the United States. Use postcodes (area, district, sector) format for United Kingdom.

For this key, the connector:

  • Trims leading and trailing whitespace

  • Converts to lower-case

  • Removes whitespace from lower-case for United Kingdom

  • Trims to five digits for United States

  • Hashes data as SHA-256

Country Code

COUNTRY

A two-letter country code in ISO 3166-1 alpha-2 format.

For this key, the connector:

  • Trims leading and trailing whitespace

  • Converts to lower-case

  • Hashes data as SHA-256

Mobile Advertiser ID

MADID

For this key, the connector:

  • Trims leading and trailing whitespace

  • Converts to lower-case

  • Keeps hyphens

  • Hashes data as SHA-256