Send data to Meta Ads Manager¶
Meta Ads Manager is a unified ad creation tool that your brand can use to create and publish ads to Facebook, Messenger, Instagram and the Meta Audience Network.
Your brand can send the following custom audiences and offline events to Meta Ads Manager:
Custom audiences help find who can be activated from Facebook, Facebook Messenger, Instagram, and WhatsApp.
Offline events help your brand track offline conversions from your marketing campaigns. Offline events are matched with audiences in Facebook, Facebook Messenger, Instagram, and WhatsApp.
Important
Only offline transactions that have occurred within the previous seven days may be sent to Meta Ads Manager.
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:
Removes existing customers from an audience without resetting your ad set’s learning phase when an audience is part of active ad sets.
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.
This topic describes the steps that are required to send customer data to Meta Ads Manager from Amperity:
How this destination works¶
You can 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 on Meta Ads Manager.
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.
A Meta Ads Manager destination works like this:
|
Use a query or segment to build a custom audience. |
|
Configure the Meta Ads Manager destination and data template. |
|
Send a test set of first-party data from Amperity, and then from within Meta Ads Manager verify that this data is available from Meta Ads Manager. 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 Meta Ads Manager. Meta Ads Manager uses OAuth to grant access to Amperity. You may need to reauthorize OAuth if the token expires or is removed. |
|
Build ads for that audience in Meta Ads Manager. |
About 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 . |
Get details¶
Meta Ads Manager requires the following configuration details:
|
The account ID. How do I find Facebook Ads account information? You can find all of this information and perform all of the required steps from within Facebook Business Manager . Click Business Settings, then Ad Accounts, and then the Facebook Ads account name. The account ID is visible under Details. Note You may use the same credentials to send offline events. |
|
|
The custom audience name and customer file source settings. The custom audience name is visible from Meta Ads Manager. This name should be clear and understandable to users of Meta Ads Manager. The custom audience name will be created if it does not exist. The customer file source specifies if the data was provided by users, provided by partners, or provided from both users and partners. Note The customer file source maps directly to the
|
|
|
Acccept the custom audience terms of service . Important Terms of service must be signed by each business user that is associated with your Facebook Ads account. |
|
|
Authorize Amperity to send data to the customer’s Facebook Ads account. This requires activation in the Amperity Meta Ads Manager account and approval in the customer’s Meta Ads Manager account. Note You may need to reauthorize Amperity at various intervals. |
|
|
Meta Ads Manager offline events only Datasets allow you to connect and manage event data from different sources—such as from websites, mobile apps, physical store locations or business chats––from one location. A dataset ID must be configured in Meta Ads Manager to support sending send offline events from Amperity. |
Terms of service¶
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.
The permissions error that you may see is similar to:
Permissions error: To create or edit an audience with an uploaded customer list,
please agree to the Custom Audience terms at
https://business.facebook.com/ads/manage/customaudiences/tos/?act=1234567890123456.
To resolve this error the terms of service must be signed by a business user who has a role in your Facebook Ads account.
Configure OAuth¶
OAuth is an open standard for access delegation, commonly used to grant websites or applications access to information on other websites.
Use OAuth to configure Amperity to send customer data to Meta Ads Manager.
To configure OAuth
|
|
Open the Destinations tab and click Add Destination. The Add Destination dialog box opens. Select Meta Ads Manager from the Plugin drop-down, and then from the Credential drop-down, select Create a new credential. This opens the Create New Credential dialog box. |
|
|
In the Create New Credential dialog box, click “Generate authorization URL”. Copy the URL, and then provide the URL to a user who has credentials that allow access to Meta Ads Manager. The user must log in and complete the steps required by the OAuth process for Meta Ads Manager. After this is completed, you will be redirected to the Credentials page in Amperity. Verify the credential is on the page, and then return to the Destinations tab. |
|
|
Open the Destinations tab and click Add Destination. The Add Destination dialog box opens. Select Meta Ads Manager from the Plugin drop-down, and then from the Credential drop-down, select the credential that is authorized to access Meta Ads Manager. Note The value for the Refresh Token setting is updated automatically after you select the credential. |
Custom audiences¶
Custom audiences help find people who already know about or have engaged with your brand. Use custom audiences for re-marketing, finding potential repeat customers, and finding lookalike audiences.
Add destination¶
Configure Amperity to send customer data directly to Meta Ads Manager.
Warning
Amperity must be authorized to send data to your Meta Ads Manager account prior to configuring the destination.
To add a destination
|
|
Open the Destinations tab to configure a destination for Meta Ads Manager. Click the Add Destination button to open the Destination dialog box. 
Enter a name for the destination and provide a description. For example: “Meta Ads Manager” and “This sends customer data to Meta Ads Manager”. From the Plugin drop-down, start typing “face” to filter the list, and then select Meta Ads Manager. |
||||||||
|
|
Credentials allow Amperity to connect to Meta Ads Manager. The credential type is set automatically. You may use an existing credential or you may add a new one. 
Select an existing credential from the Credential drop-down. – or – Select Create a new credential from the Credential drop-down. This opens the Credential dialog box. 
Enter the name for the credential, and then add a description. Steps to configure OAuth
|
||||||||
|
|
Each destination has settings that define how Amperity will deliver data to Meta Ads Manager. These settings are listed under the Settings section of the Destination dialog box. 
The following settings are specific to Meta Ads Manager:
|
||||||||
|
|
Business users are assigned to the Amp360 User and/or AmpIQ User policies. (Amp360 User allows access to queries and orchestrations and AmpIQ User allows access to segments and campaigns.) A business user cannot select a destination that is not visible to them. Business users – including users assigned to the DataGrid Operator policy – may have restricted access to PII. What is restricted access to PII? Restricted PII access is enabled when the Restrict PII Access policy option that prevents users who are assigned to that option from viewing data that is marked as PII anywhere in Amperity and from sending that data to any downstream workflow. You can make this destination visible to orchestrations and allow users with restricted access to PII to use this destination by enabling one (or both) of the following options: 
Note To allow business users to use this destination with campaigns, you must enable the Make available to campaigns option within the data template. This allows users to send campaign results from Amperity to Meta Ads Manager. The other two settings may be configured within the data template instead of the destination. |
||||||||
|
Review all settings, and then click Save. 
Important You must configure a data template for this destination before you can send data to Meta Ads Manager. |
Add data template¶
A data template defines how columns in Amperity data structures are sent to downstream workflows. A data template is part of the configuration for sending query and segment results from Amperity to an external location.
To add a data template
|
|
From the Destinations tab, open the menu for a destination that is configured for Meta Ads Manager, and then select Add data template. This opens the Add Data Template dialog box. 
Enter the name of the data template and a description. For example: “Meta Ads Manager” and “Send customer data to Meta Ads Manager.”. |
|
|
Verify business user access to queries and orchestrations and access to segments and campaigns. A business user may also have restricted access to PII, which prevents them from viewing and sending customer profile data. 
If business user access was not configured as part of the destination, you may configure access from the data template. Important To allow business users to use this destination with campaigns, you must enable the Make available to campaigns option. This allows users to send campaign results from Amperity to Meta Ads Manager. If you enable this option, the data extension settings require using campaign name and group name template variables to associate the name of the data extension to your campaign. |
|
|
Verify all configuration settings. 
Note When the account ID, custom audience, and the customer file source settings were are not configured as part of the destination, you must configure them as part of the data template before making this destination available to campaigns. |
|
|
Review all settings, and then click Save.
After you have saved the data template, and depending on how you configured it, business users can send query results and/or send campaigns to Meta Ads Manager. |
Offline events¶
Use offline events to track offline conversions from your marketing campaigns.
For example: When did a customer purchase? What did a customer purchase? Was it from a store or a website? How many items were purchased? Was there more than one purchase? What was the total revenue for each purchase?
Note
Offline events are not immediately available in Meta Ads Manager. Allow for up to 24 hours after the point at which Amperity has finished sending offline events for them to be available.
Build a query¶
Use a query to build a combination of data from the Unified_Itemized_Transactions and Customer_360 tables to represent the set of offline events that your brand wants to use within Meta Ads Manager. A query that collects offline events for use in Meta Ads Manager is similar to:
SELECT
c360.amperity_id AS external_id
,c360.email AS email
,c360.phone AS phone
,c360.given_name AS given_name
,c360.surname AS surname
,c360.birthdate AS birthdate
,c360.gender AS gender
,c360.city AS city
,c360.state AS state
,c360.postal AS postal
,c360.country AS country
,uit.order_id AS order_id
,uit.item_quantity AS quantity
,uit.product_id AS product_id
,uit.order_datetime AS timestamp
,CAST(uit.item_revenue / uit.item_quantity AS REAL) AS price
FROM Unified_Itemized_Transactions uit
LEFT JOIN Customer_360 c360 ON uit.amperity_id = c360.amperity_id
WHERE uit.order_datetime > (CURRENT_DATE - interval '7' day)
and MUST contain the following fields: external_id, order_id, quantity, email OR phone (one of which is required; both email addresses and phone numbers may be sent), product_id, timestamp, and price.
You may include the following fields for better matches: given_name, surname, birthdate, gender, city, state, postal, and country.
Note
The only field that must be renamed is amperity_id to external_id.
Fields that contain PII – email and phone, for example – will have one-way SHA-256 hashing applied to them.
The number of rows in the query within Amperity will not be the same as the number of events that are uploaded to Meta Ads Manager. This is because itemized transactions within the query are grouped by order_id as the data is sent to Meta Ads Manager. This ensures that events describe the total transaction, including the total value of the event.
Note
The phone number must be in e164 format. If your customer 360 database is not already standardized for e164 format, use the following line instead of ,c360.phone AS phone:
,CONCAT('+1','',REGEXP_REPLACE(c360.phone,'[$\D\s]','')) AS phone
Add destination¶
Configure Amperity to send customer data directly to Meta Ads Manager.
Warning
Amperity must be authorized to send data to your Meta Ads Manager account prior to configuring the destination.
To add a destination
|
|
Open the Destinations tab to configure a destination for Meta Ads Manager. Click the Add Destination button to open the Destination dialog box. 
Enter the name of the destination and a description. For example: “Meta Ads Manager offline events” and “Send offline events to Meta Ads Manager.”. |
|
|
Credentials allow Amperity to connect to Meta Ads Manager. The credential type is set automatically. You may use an existing credential or you may add a new one. 
Select an existing credential from the Credential drop-down. – or – Select Create a new credential from the Credential drop-down. This opens the Credential dialog box. Meta Ads Manager requires using OAuth to authorize Amperity to send offline events to your Meta Ads Manager account. Note You may use the same credentials custom audiences and offline events. |
|
|
Each destination has settings that define how Amperity will deliver data to Meta Ads Manager. These settings are listed under the Settings section of the Destination dialog box. 
Datasets allow you to connect and manage event data from different sources—such as from websites, mobile apps, physical store locations or business chats––from one location. |
|
|
Business users are assigned to the Amp360 User and/or AmpIQ User policies. (Amp360 User allows access to queries and orchestrations and AmpIQ User allows access to segments and campaigns.) A business user cannot select a destination that is not visible to them. Business users – including users assigned to the DataGrid Operator policy – may have restricted access to PII. What is restricted access to PII? Restricted PII access is enabled when the Restrict PII Access policy option that prevents users who are assigned to that option from viewing data that is marked as PII anywhere in Amperity and from sending that data to any downstream workflow. You can make this destination visible to orchestrations and allow users with restricted access to PII to use this destination by enabling one (or both) of the following options:
|
|
|
Review all settings, and then click Save.
Important You must configure a data template for this destination before you can send data to Meta Ads Manager. |
Add data template¶
Offline events must be sent using a query and orchestration. The data template associated with offline events should not be made available to the Campaigns editor.
To add a data template
|
|
From the Destinations tab, open the menu for a destination that is configured for Meta Ads Manager, and then select Add data template. This opens the Add Data Template dialog box. 
Enter the name of the data template and a description. For example: “Meta Ads Manager offline events” and “Send offline events to Meta Ads Manager.”. |
|
|
Verify business user access to queries and orchestrations and access to segments and campaigns. A business user may also have restricted access to PII, which prevents them from viewing and sending customer profile data. 
If business user access was not configured as part of the destination, you may configure access from the data template. |
|
|
Verify all configuration settings. 
Note If the dataset ID is not specified in the data template it must be specified at orchestration. |
|
|
Review all settings, and then click Save.
After you have saved the data template, and depending on how you configured it, business users can send query results and/or send campaigns to Meta Ads Manager. |
Workflow actions¶
A workflow will occasionally show an error that describes what prevented a workflow from completing successfully. These first appear as alerts in the notifications pane. The alert describes the error, and then links to the Workflows tab.
Open the Workflows tab to review a list of workflow actions, choose an action to resolve the workflow error, and then follow the steps that are shown.
|
|
You may receive a notifications error for a configured Meta Ads Manager destination. This appears as an alert in the notifications pane on the Destinations tab. 
If you receive a notification error, review the details, and then click the View Workflow link to open this notification error in the Workflows page. |
|
|
On the Workflows page, review the individual steps to determine which step(s) have errors that require your attention, and then click Show Resolutions to review the list of workflow actions that were generated for this error. 
|
|
|
A list of individual workflow actions are shown. Review the list to identify which action you should take. 
Some workflow actions are common across workflows and will often be available, such as retrying a specific task within a workflow or restarting a workflow. These types of actions can often resolve an error. In certain cases, actions are specific and are shown when certain conditions exist in your tenant. These types of actions typically must be resolved and may require steps that must be done upstream or downstream from your Amperity workflow. Amperity provides a series of workflow actions that can help resolve specific issues that may arise with Meta Ads Manager, including: |
|
|
Select a workflow action from the list of actions, and then review the steps for resolving that error. 
After you have completed the steps in the workflow action, click Continue to re-run the workflow. |
Cannot create ads¶
The advertising account that is used by this workflow must have permission to create ads.
To resolve this error, update the user permissions in Meta Ads Manager to ensure that the advertising account can create ads.
Log into Meta Ads Manager and verify the user permissions for the account.
Update the user permissions to ensure that the Create and edit ads permission is assigned to the advertising account used by this workflow.
Return to the workflow action, and then click Resolve to retry this workflow.
EXTERN_ID is missing¶
An EXTERN_ID is a unique ID used within Meta Ads Manager, such as a loyalty ID, a customer ID, an external ID, or the Amperity ID.
Amperity will be unable to send orchestrations or campaigns when EXTERN_ID is not included within an audience that is sent to Meta Ads Manager.
For campaigns
To resolve this error, verify that EXTERN_ID is included in the list of attributes that are being sent to Meta Ads Manager.
Open the Campaigns page, and then open the segment used with this workflow.
Verify that EXTERN_ID is included in the list of attributes for each recipient group that sends audiences to Meta Ads Manager. Update the list of attributes for each recipient group if required.
Return to the workflow action, and then click Resolve to retry this workflow.
For orchestrations
To resolve this error, verify that EXTERN_ID is included in the query results.
Open the Queries page, and then open the query used with this workflow.
Verify that EXTERN_ID is included in the query results. Update the query if required.
Return to the workflow action, and then click Resolve to retry this workflow.
Invalid credentials¶
The credentials that are defined in Amperity are invalid.
To resolve this error, verify that the credentials required by this workflow are valid.
Open the Credentials page.
Review the details for the credentials used with this workflow. Update the credentials for Meta Ads Manager if required.
Return to the workflow action, and then click Resolve to retry this workflow.
Maximum custom audiences exceeded¶
Meta Ads Manager supports having up to 500 custom audiences in your account at any given time. Amperity will be unable to create custom audiences when this limit is exceeded.
To resolve this error, verify the number of custom-audiences associated with your Meta Ads Manager account.
Log into Meta Ads Manager and verify the number of custom audiences that are associated with your Meta Ads Manager account.
Remove custom audiences that are not in active use.
Return to the workflow action, and then click Resolve to retry this workflow.
Must agree to Facebook terms¶
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.
When the business user has not agreed to Facebook terms, an error similar to the following is shown:
Permissions error: To create or edit an audience with an uploaded customer list,
please agree to the Custom Audience terms at
https://business.facebook.com/ads/manage/customaudiences/tos/?act=1234567890123456.
To resolve this error, log into Meta Ads Manager as the business user associated with this workflow and agree to the terms of service.
Follow the instructions in the error message, and then open the provided link in a new tab.
Log in as the business user associated with this workflow, and then agree to the Facebook terms of service.
Return to the workflow action, and then click Resolve to retry this workflow.
Must belong to business account¶
The advertising account used to enable workflows to be sent to Meta Ads Manager from Amperity requires the advertising account to also belong to a business account. When an advertising account does not also belong to a business account, Amperity workflows will be unable to create or edit a custom audience.
To resolve this error, verify that the advertising account also belongs to a business account.
Log into Meta Ads Manager and verify the configuration for the advertising account to ensure that it also belongs to a business account.
Return to the workflow action, and then click Resolve to retry this workflow.
Security challenge¶
Sometimes Meta Ads Manager will issue a security challenge to the advertising account and/or business account associated with this workflow.
To resolve this error, complete the steps that are required to resolve the security challenge.
Log into Meta Ads Manager using the link provided in the workflow action, and then follow the instructions to resolve the security challenge.
Return to the workflow action, and then click Resolve to retry this workflow.
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: |
Email Addresses |
For this key, the connector:
|
|
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:
|
Gender |
GEN |
For this key, the connector:
|
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 |
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 |
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 |
Last Name |
LN |
This key supports special characters and non-Roman alphabet characters. For this key, the connector:
|
First Name |
FN |
This key supports special characters and non-Roman alphabet characters. For this key, the connector:
|
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:
|
City |
CT |
For this key, the connector:
|
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:
|
Country Code |
COUNTRY |
A two-letter country code in ISO 3166-1 alpha-2 format. For this key, the connector:
|
Mobile Advertiser ID |
MADID |
For this key, the connector:
|