Send data to Braze¶
Braze is a leading marketing automation platform that allows users to create custom experiences based on sophisticated customer attributes and segments, then map those experiences to campaigns.
Amperity can send customer profile and custom attributes to Braze, attaching the data that is sent from Amperity to customer profiles that already exist in Braze.
This topic describes the steps that are required to send custom attributes to Braze from Amperity:
About custom attributes¶
Attributes in Braze describe your customers.
Profile attributes describe who your customers are. For example: names, birthdates, email addresses, and phone numbers.
Custom attributes describe how your customers have interacted with your brand. For example: purchase histories, loyalty status, and value tiers.
When user profile fields and custom attributes are available in Braze they can be used to build out audience segments and to apply personalization to your campaigns.
Customer profiles¶
Attributes in Braze describe your customers.
Profile attributes describe who your customers are. For example: names, birthdates, email addresses, and phone numbers.
Custom attributes describe how your customers have interacted with your brand. For example: purchase histories, loyalty status, and value tiers.
When user profile fields and custom attributes are available in Braze they can be used to build out audience segments and to apply personalization to your campaigns.
What about email and phone subscription status?
Braze uses two fields to track email and phone subscription status: email_subscribe and push_subscribe. The values for these fields are not modified by Amperity even when the fields are sent from Amperity with the correct values. Braze is your source of truth for customer consent and for tracking email and phone subscription status.
The following table describes the default user profile fields that are most commonly updated from Amperity:
Braze default field |
Amperity field name |
Description |
|---|---|---|
external_id |
varies |
Required. The external_id is a unique identifer for user profiles in Braze. The external_id is a unique identifier that exists in another system, such as the Amperity ID, a loyalty ID, or some other unique customer identifier. |
first_name |
given_name |
Optional. |
last_name |
surname |
Optional. |
Optional. |
||
phone |
phone |
Optional. |
home_city |
city |
Optional. |
country |
country |
Optional. Must be in ISO 3166-1 alpha-2 format. |
dob |
birthdate |
Optional. Must be in “YYYY-MM-DD” format. |
gender |
gender |
Optional. Accepted values: “M”, “F”, “O” (other), “N” (not applicable), “P” (prefer not to say), or NULL. |
Note
Default user profile fields also exist for alias_name, alias_label, current_location, date_of_first_session, date_of_last_session, email_open_tracking_disabled, email_click_tracking_disabled, facebook, language, marked_email_as_spam_at, push_tokens, subscription_groups, time_zone, and twitter.
These fields are not commonly sent to Braze from Amperity, but if your brand chooses to update these user profile fields from Amperity, be sure to use the exact name of the default field name, send the correct value (or values), and to use lowercase.
Custom attributes¶
Custom attributes in Braze are represented by a set of custom-named fields. The names of these fields are determined by your brand. They may already exist in Braze, in which case you will want to shape the output that is sent from Amperity to align to the names you already have.
The names of custom attributes that can be managed by Amperity are defined by your brand. The names are strings, may contain hyphens, spaces, or underscores, may include numbers, and may contain a mix of lowercase and uppercase letters. For example, custom attribute can have names that:
Already exist within your organization.
Are exactly the same as Amperity standard output, such as “One and Done” or “L12M Monetary” (the “monetary” component of an RFM score), or “Early Repeat Purchaser”.
Align to marketing goals and/or terminology that exists within your brand’s segmentation strategy.
Verify the names of custom attributes that will be sent to Braze from Amperity. Amperity will add a custom attribute whenever there isn’t a matching name.
Tip
Avoid sending custom attributes as duplicates of default user profile fields. For example, birthdates should be sent to Braze as a user profile field named “dob”. If they are sent as “birthday”, “Birthdate”, or any other string, a custom attribute will be created and the values in the “dob” field will not be updated.
Important
Your brand’s list of custom attributes should be a list that is mostly static, remains stable over time, and is focused on your most valuable customers.
Only update custom attributes for customers to which your brand is currently engaged. Define an audience in Amperity that is some combination of “high value” (historical or predicted), “active” (has purchased recently), and are “contactable” (with an opt-in status of true for phone numbers and/or email addresses).
This will help ensure that you are only updating custom attributes for your most valuable customers. Custom attributes will be updated only for those customers have a matching “external_id” or “braze_id” within Braze.
About data points¶
Braze uses data points to determine when to update segment membership, to identify which types of messages should be sent, and how to apply message personalization.
You can send custom attributes to Braze from Amperity by attaching attributes from your customer profiles in Amperity, such as first and last names, email addresses, phone numbers, physical locations, SMS and email consent status, purchase histories, and so on.
Amperity tracks changes as they are sent to Braze and only sends list membership and attribute that have changed since the previous update.
Note
Data points are part of the billing and pricing structure in your Braze contract. Some data points are non-billable; many data points are billable.
Review the lists of non-billable and billable data points , and then review those lists against the attributes you will send to Braze from Amperity to understand which of those attributes are considered billable or non-billable data points.
Important
Connected Content does not write data to user profiles, which means you can use Connected Content to dynamically populate values into messages without consuming data points.
Audience profile updates¶
Profile attributes, such as email, birthdate, address, and phone, contain stable values. Most customers remain at the same address and have the same phone number for years. An individual customer’s birthdate never changes. When customer profile attributes do change your brand will always want to update any downstream audience profiles.
Behavioral attributes, both historical and predicted, are more likely to contain values that change frequently. Behavioral attributes should be carefully evaluated before including them within audience profiles. This will help ensure that updates related to behavioral attributes are adding value to your brand’s downstream business use case(s).
What types of attributes have values that change frequently?
The following types of attributes contain values that change frequently:
Relative date values |
Attributes with relative date values typically contain a rolling value that is updated daily. For example, the Transaction Attributes Extended table contains an attribute named Days Since Latest Order. This is a useful attribute that counts the number of days that have elapsed since an individual customer last placed an order with your brand. Today that value might be “10” and tomorrow, if that customer has not purchased, will be “11”. Using Days Since Latest Order as an attribute within customer profiles ensures that every customer profile associated with a customer who did not purchase during the previous X days will get an updated profile. For relative date values, consider building a custom attribute that converts the ranges into a list of values. For example, you can assign a single value to represent a range of values. Less than 30 days is “green”, less than 90 days is “yellow”, and less than 365 days is “red”. Include the custom attribute to capture the range of days as an indicator instead of the specific relative value. |
High-precision values |
High-precision values are found in attributes that contain floating points, decimals, and percentages. These types of values—1.09413481, 345.47 or .34—often change slightly, but in a way that offers little value to the downstream business use case. For example, predictive attributes are refreshed daily. Predicted CLV during the next 365 days might be $345.37 on one day and $348.75 a few days later. Instead of using predicted CLV in an audience profile, consider using predicted lifecycle status (active, at risk, etc.) or predicted value tier (gold, bronze, etc.), both of which are less likely to change because they represent a range of predicted behaviors instead of a specific predicted value. |
Calculated attribute values |
Many attributes are calculated by Amperity, including all time period rollups. For example, the Transaction Attributes Extended table contains an attribute named L6M Order Revenue. This attribute returns the order revenue for each customer over a rolling 6-month timeframe. This attribute is refreshed on a daily basis and the value is updated each time a customer makes a purchase. Instead of using the time period rollup attributes directly you can build a custom attribute to define thresholds or to return a yes or no. For example, instead of using the specific revenue amount for L6M Order Revenue you could build a custom attribute that returns true when the value for L6M Order Revenue is greater than $500. |
Customer attributes table¶
Build a table that contains all of the attributes in Braze that your brand wants to manage from Amperity. The columns in this table must be correctly mapped to requirements for user profile fields and should contain the list of custom attributes that will be maintained.
To add a Braze customer attributes table
|
Open your customer 360 database and add a table named “Braze Customer Attributes”. Use SQL to define the default user profile fields that are required by Braze: SELECT
mc.amperity_id
,mc.amperity_id AS external_id
,mc.given_name AS first_name
,mc.surname AS last_name
,mc.email
,mc.phone
,mc.city AS home_city
,mc.country
,mc.birthdate AS dob
,mc.gender
FROM Merged_Customers mc
You may include custom attributes that map to other fields in your customer 360. For example, to use transaction attributes as custom attributes in Braze you can extend the table to include fields from the Transaction Attributes Extended table: SELECT
mc.amperity_id
,mc.amperity_id AS external_id
,mc.given_name AS first_name
,mc.surname AS last_name
,mc.email
,mc.phone
,mc.city AS home_city
,mc.country
,mc.birthdate AS dob
,mc.gender
,ta.L30D_purchase_channels
,ta.L30D_order_revenue
,ta.L30D_order_frequency
,ta.L3M_purchase_channels
,ta.L3M_order_revenue
,ta.L3M_order_frequency
,ta.L12M_rfm_score
,ta.L12M_recency
,ta.L12M_frequency
,ta.L12M_monetary
,ta.lifetime_order_revenue
,ta.one_and_done
,ta.multi_purchase_channel
,ta.first_to_second_order_days
,ta.days_since_latest_order
,ta.latest_order_datetime
,ta.early_repeat_purchaser
FROM Merged_Customers mc
LEFT JOIN Transaction_Attributes_Extended ta
ON mc.amperity_id = ta.amperity_id
LEFT JOIN Customer_Attributes ca
ON mc.amperity_id = ca.amperity_id
|
|
Validate the table, and then click Next. Name the table “Braze Customer Attributes”, and then save the table. Verify that the table is accessible to the Segment Editor and to the Edit Attributes editor within campaigns. |
Get details¶
Braze requires the following configuration details:
|
Configuration details for Braze.
|
Add destination¶
Configure Amperity to send custom attributes directly to Braze.
To add a destination
|
|
Open the Destinations tab to configure a destination for Braze. Click the Add Destination button to open the Destination dialog box. 
Enter a name for the destination and provide a description. For example: “Braze” and “This sends custom attributes to Braze”. From the Plugin drop-down, start typing “br” to filter the list, and then select Braze. |
|
|
Credentials allow Amperity to connect to Braze. 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. Add the API key for your instance of Braze. 
When finished, click Save. |
|
Each destination has settings that define how Amperity will deliver data to Braze. These settings are listed under the Settings section of the Destination dialog box. 
Select the Braze instance . Select the user identifier. The external_id is a unique identifier for your customers, such as the Amperity ID. The braze_id is a unique identifier for existing Braze customers. To update audience profiles only when one (or more) values change, enable the Only send updated audience profiles option. Note Use the Only send updated audience profiles option to configure Amperity to update audience profiles only when one (or more) values within a profile have changed. An update to an individual value in an audience profile requires updating the entire audience profile. For use cases that require sending attributes that have values that are expected to change frequently, consider using additional queries to orchestrate specific sets of attributes at defined intervals so that your brand can maintain these values independently of your customer profiles. |
|
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 Available to campaigns option within the data template. This allows users to send campaign results from Amperity to Braze. 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 Braze. |
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 Braze, 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: “Braze” and “Send custom attributes to Braze.”. |
|
|
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 When the settings required by Braze 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 Braze. |
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 page 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 Braze 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 Braze, 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 rerun the 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 Braze if required.
Return to the workflow action, and then click Resolve to retry this workflow.
Missing required field¶
A unique identifier must be provided to Braze. There are two options:
Recommended. The external_id , which is a unique identifier for your customers. This may be the Amperity ID or it may be some other unique identifier.
The braze_id , which is a unique identifier for existing Braze customers and may be available when Braze is also a data source for your tenant.
For campaigns
To resolve this error, verify that “external_id” or “braze_id” are included in the list of attributes that are being sent to Braze.
Open the Campaigns page, and then open the segment used with this workflow.
Verify that “external_id” or “braze_id” is included in the list of attributes for each treatment group that sends audiences to Braze. Update the list of attributes for each treatment group if required.
Return to the workflow action, and then click Resolve to retry this workflow.
For orchestrations
To resolve this error, verify that “external_id” or “braze_id” are included in the query results.
Open the Queries page, and then open the query used with this workflow.
Verify that “external_id” or “braze_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.
Status 401 error¶
A “Status 401” error is an authorization error: Amperity was unable to connect to Braze. This may be a transient error; however, this type of error is more likely caused by a configuration issue within Amperity. For example, the currently-configured API key is invalid because the API key was rotated.
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 Braze if required.
Return to the workflow action, and then click Resolve to retry this workflow.