Send audiences to MoEngage Attributes

MoEngage is a cross-channel customer engagement platform built for marketers and product owners who value agility over complexity. Use real-time insights and personalized cross-channel communications and adapt to evolving customer expectations.

Note

This destination uses the MoEngage Data API , sending users with Bulk Import .

Beta

The MoEngage Attributes connector is in beta. Contact your Amperity representative to learn more.

The steps required to configure campaigns to send customer attributes to MoEngage.

Note

Ask your DataGrid Operator or your Amperity representative for help configuring MoEngage as a destination to which you can send campaigns for customer activation.

Caution

This destination is available for sending campaign audiences to MoEngage after it is configured by a Datagrid Operator or your Amperity representative.

If this destination cannot be selected from the campaigns editor or activations canvas ask your Datagrid Operator or Amperity representative to configure a destination for sending campaign audiences to MoEngage.

Build a segment

Use the Segment Editor to build any audience using a series of drop-downs and picklists.

As you define the attribute profile for an audience be sure to refresh segment insights to view audience size and to see the value it brings to your business.

When the segment is ready, activate it, and then use it use it in a campaign to send to your preferred destinations for customer activation.

About segments that use the sub-audience editor

You can use any attribute that is in your customer 360 database to define your audience.

When sending the list of customers who belong to this audience to MoEngage as part of a campaign you must choose specific attributes to send.

MoEngage supports the following attributes: customer attributes.

Important

Validate the audience with MoEngage by using a sample audience with a very small membership. For example: 10 or 100 members or the minimum audience size recommended by MoEngage. Send the sample audience to MoEngage and verify the sample audience is correct in MoEngage. Make adjustments if necessary. Only send full audiences after validation is complete.

Add to a campaign

Use the campaign editor to configure Amperity to send data to MoEngage. Add a segment, define exclusions and sub-audiences, and then define each audience sent to MoEngage.

Step 1.

Open the Campaign Editor. This is available from the Campaigns page. Click the Create campaign button in the top right corner of the page.
Step 2.

Assign MoEngage as a destination for at least one treatment group.

Note

You may need to edit the attributes for the sub-audience to ensure Amperity is sending the right data to MoEngage.
Step 3.

Click Edit attributes to review the attributes that Amperity sends to MoEngage.

The attributes sent are the customer_id attribute and every other attribute in the treatment, which MoEngage stores as a user attribute named after the attribute.

Amperity pre-selects the list of attributes sent to MoEngage. The Edit attributes page for MoEngage is similar to:

Note

The Merged Customers table is the default table for sending data to MoEngage, even though segments are often built against the Customer 360 table. This is by design. The Merged Customers table is the underlying table for customer profile data and is the source for all customer profile data that exists within the Customer 360 table.

Configure default attributes

Each unique destination configured to send treatment group audiences to MoEngage has a set of default attributes.

Configure default attributes by clicking the Default attributes link next to the Create campaign button on the Campaigns page.

The source table defaults to the Merged Customers table for most attributes. This is configurable.

MoEngage requires the customer_id field. Every other field is sent as a MoEngage user attribute named after the field.

Source attribute

Required?

Destination attribute

customer_id

Yes

The MoEngage customer ID for the customer, which MoEngage uses to find the user. A send without this field fails before any data is sent.

Map the field that holds the ID your app or website uses for each user in MoEngage. This is not necessarily the Amperity ID.

Additional attributes

No

Each additional field is sent as a user attribute with the field’s name. To fill a standard MoEngage attribute, name the field with that attribute’s key, such as u_em for email, u_fn for first name, or u_ln for last name. Any other name creates or updates a custom attribute.

Each campaign send sends only the customers whose attributes changed since the last send.

The customer ID is the unique ID that MoEngage identifies a user by. It is usually the ID that your app or website passes to the MoEngage SDK when a user logs in, which is not necessarily the Amperity ID. Confirm which field in Amperity holds the same value before you send, and alias that field as customer_id in the query, for example SELECT loyalty_id AS customer_id.

Amperity sends each customer ID as text, after removing leading and trailing whitespace, and MoEngage matches it exactly. When the field holds a floating-point number, such as a DOUBLE, or a DECIMAL with digits after the decimal point, convert it in the query, for example CAST(CAST(loyalty_id AS BIGINT) AS VARCHAR) AS customer_id. Otherwise the ID 12345 is sent as 12345.0 or 12345.00 and does not match the user in MoEngage.

Return one row for each customer ID. Amperity does not send these rows:

  • A row whose customer ID is null or empty. Amperity skips the row without an error, and counts it with the rows sent from cache.

  • A row whose customer ID repeats another row’s customer ID. Amperity keeps one of the rows and skips the others without an error. Which row it keeps is not determined.

  • A row whose customer ID MoEngage does not accept. This is a customer ID that contains only whitespace, is one character long, or is a placeholder value such as unknown, guest, null, none, n/a, 0, or -1. These values are compared without regard to case. MoEngage lists the values it does not accept in its Data API overview . Amperity reports the row as failed instead of sending it.

User attributes

Every column in the query results except customer_id is sent to MoEngage as a user attribute. The column name becomes the attribute name, and the column value becomes the attribute value.

  • Standard attributes need MoEngage’s attribute names. To fill a standard MoEngage attribute, name the column with that attribute’s key, for example SELECT email AS u_em. A column with any other name creates or updates a custom attribute with that name.

    Column name

    Standard attribute

    u_em

    Email

    u_mb

    Mobile number

    u_fn

    First name

    u_ln

    Last name

    u_n

    Full name

    u_gd

    Gender

    u_bd

    Birthdate

    MoEngage lists every standard attribute and its format in the Bulk Import reference.

  • Values are sent as your query returns them. Amperity does not convert or check attribute values. A number is sent as a number, a Boolean value as a Boolean value, and text as text. Build the exact value that you want to see in MoEngage in your query.

  • Send dates as ISO 8601 text. MoEngage documents date attributes, including u_bd, in ISO 8601 format with a time and a time zone, for example 2020-05-31T03:47:35Z. Amperity sends a date the way the query returns it, so convert a date that is in another form, such as 05/31/2020 or a number of seconds since 1970, in the query. To convert a timestamp that is in UTC, use DATE_FORMAT(birthdate, '%Y-%m-%dT%H:%i:%sZ') AS u_bd.

  • A null value clears the attribute. When a column is null for a row, Amperity asks MoEngage to remove that attribute from the user, so that MoEngage matches Amperity. This also clears a value that another source, such as a MoEngage SDK in your app or website, set for that attribute. A column that is empty text, rather than null, is sent as empty text.

  • Some attribute names are not accepted. MoEngage does not accept id, _id, or an empty name as an attribute name. A send whose query results have a column with one of these names fails before any data is sent. Rename the column.

Caution

MoEngage reserves the moe_ prefix for its own attributes, and says that it can block a workspace that uses the prefix for custom attributes. Amperity does not check for the prefix, because some standard attributes, such as moe_unsubscribe, use it. Name a column with moe_ only when it fills a MoEngage standard attribute.

Caution

Amperity owns the attributes that it sends. When a row changes, Amperity sends all of the row’s attributes, which overwrites the values that another source, such as a MoEngage SDK, set for the same attributes. Do not send an attribute that another source should own.

Caution

Amperity sends only the rows that are in the query results. A user who drops out of the query results is not sent again, so the attributes that user already has stay in MoEngage, holding their last values. Removing a column from the query has the same effect: the attribute keeps its last value on every user who has it.

To clear an attribute for users who no longer qualify, keep them in the query results and return a null value for that attribute.