Send query results to Meta Ads Manager¶

You can use queries and orchestrations to build custom audiences in Meta Ads Manager. Send customer information, such as email addresses, phone numbers, names, birthdates, gender, city, state, postal code, and mobile advertising IDs, from Amperity to find customer matches.

Use audiences in Meta Ads Manager to advertise to customers on Facebook, Instagram, and Messenger, and to use Meta Audience Network to extend your advertising beyond Facebook to reach new audiences on apps and mobile devices, such as WhatsApp.

Build custom audiences on Meta Ads Manager using data from Amperity.

A Meta Ads Manager destination works like this:

Build a custom audience using a query
Add orchestration
Run orchestration

Important

The custom audience terms of service must be signed by each business user that is associated with your Facebook Ads account. If the terms of service are not signed, a permissions error will prevent Amperity from sending data to Facebook Ads.

Meta Ads Manager uses OAuth to grant access to Amperity. You will need to reauthorize OAuth if the token expires or is removed.

Ask your DataGrid Operator to help resolve these issues if they occur.
Note

This destination uses two APIs: Facebook Marketing API and Conversions API for Offline Events.

The Facebook Marketing API , specifically the Replace Users endpoint , is used to send audiences. This endpoint:
1. Removes existing customers from an audience without resetting your ad set’s learning phase when an audience is part of active ad sets.
2. Replaces those users with the list of customers that was sent to Meta Ads Manager from Amperity.
Offline events that occurred within the previous seven days are sent to Meta Ads Manager using the Conversions API for Offline Events .

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

Build ads in Meta Ads Manager.

What is Meta Ads Manager?

Audiences sent to Meta Ads Manager have access to Facebook, Messenger, Instagram and the Meta Audience Network.

	Use Meta Ads Manager to configure a variety of ad placements across Facebook .
	Use Meta Ads Manager to configure objectives that place ads on Instagram .
	Use Meta Ads Manager to configure objectives that place ads on Messenger .
	Use Audience Manager to reach users who are not on Facebook or Instagram, but are on mobile apps that are within the audience network. For example, creating ads that open conversation threads in WhatsApp .

Place ads on Facebook, Instagram, and Messenger; use Audience Network to extend advertising beyond Facebook to reach audiences on apps and mobile devices, such as WhatsApp.

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 Meta Ads Manager is only required one time. You can do this in the following ways:

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 Meta Ads Manager naming patterns.
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 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 AS EXTERN_ID
  ,LOWER(email) AS EMAIL
  ,CONCAT('+1','',REGEXP_REPLACE(phone,'[$\D\s]','')) AS PHONE
  ,REGEXP_REPLACE(given_name, '[^\w\s]', '') AS FN
  ,REGEXP_REPLACE(surname, '[*@/.,-_]', '') AS LN
  ,REGEXP_EXTRACT(postal,'^(\d{5})') AS ZIP
  ,LOWER(REPLACE(city, ' ', '')) AS CT
  ,UPPER(state) AS ST
  ,country AS COUNTRY
  ,birthdate AS BIRTH
  ,SUBSTR(LOWER(gender),1,1) AS GEN
FROM Merged_Customers
WHERE email IS NOT NULL
OR phone IS NOT NULL
OR (given_name IS NOT NULL
    AND surname IS NOT NULL
    AND postal IS NOT NULL
)

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 Meta Ads Manager.

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.

Note

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

To add an orchestration

From the Destinations tab, click Add Orchestration. This opens the Add Orchestration dialog box.
From the Object Type drop-down, select Query.
From the Object drop-down, select the query for which results will be sent to Meta Ads Manager.
From the Destination drop-down, select a destination that is configured for sending data to Meta Ads Manager.
From the Data Template drop-down, select a data template.
Verify all settings.
Set the workflow to Manual. (You can change this to automatic later, after verifying the end-to-end workflow.)
Click Save.

Run orchestration¶

Run the orchestration manually to validate that it works.

Important

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

To add an orchestration

From the Destinations tab, click Add Orchestration. This opens the Add Orchestration dialog box.
From the Object Type drop-down, select Query.
From the Object drop-down, select the query for which results will be sent to Meta Ads Manager.
From the Destination drop-down, select a destination that is configured for sending data to Meta Ads Manager.
From the Data Template drop-down, select a data template.
Verify all settings.
Set the workflow to Manual. (You can change this to automatic later, after verifying the end-to-end workflow.)
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