User Identifiers in Mapp Connect

Overview

Mapp Connect supports various user identifiers to streamline user event processing across different integration types and subtypes. This setup enables greater flexibility in managing user data based on unique identifiers (e.g., email addresses) and non-unique identifiers (e.g., defined in your external systems or specified as a custom attribute).

Supported Identifiers

Mapp Connect provides unique identifiers and a non-unique identifier for user events:

• Unique Identifiers:

  • userID: The Contact ID that every Mapp Engage contact gets assigned in the system upon creation.

  • email: The user’s email address.

  • mobileNumber: The mobile phone number used as an identifier.

• Non-Unique Identifiers (available only for “User” subtype events):

  • externalID: An identifier generated within an external system. In Mapp Engage, it is often referred to as user.identifier.

  • Additionally, we provide the possibility to match users by leveraging custom attributes, which enables flexible targeting and user management. To see how it works, go to the section Leveraging Custom Attributes to Match Users.

Unique Identifiers

Unique User identifiers are available for the following subtypes: wishlist, abandonedCart, recommendedproduct, automation, webpush, push, transaction, email, sms.

Pay attention to using the correct Subtype (location) while setting up the mapping. This subtype matches the event type name from the API call. The call won't be processed if there is no mapping for the event type. For example, you must define a mapping with the subtype Email to send an email. For details, see Edit Mapping.

Non-Unique Identifiers

The non-unique identifier is only available for the “User” subtype.

If multiple contacts share the same value for a non-unique identifier, any user update event will apply to all contacts with that identifier value.

Requirements and Processing Hierarchy

Unique & Non-unique Identifiers

Each user event must include at least one unique identifier to ensure proper processing. Mapp Connect processes user events using the following identifier hierarchy:

1. userID: The system first checks for a match using the userID.

2. Email: If no userID match is found, it searches by email.

3. Mobile Number: If no email match is found, it searches by mobileNumber.

4. External ID: If no mobileNumber match is found, it checks for the externalID.

Handling Missing Identifiers

If no matching identifier (e.g.,userID, email, or mobileNumber) is found, the system processes the events as follows:

1. Transaction Events: A new user profile is created.

2. User Events: A new user profile is created if the update-only import mode is either absent or explicitly set to false (the default behavior). If the update-only mode is set to true, no new user profile will be created.

   {
     "email": "user@mapp.com",
     "updateonly": "true"
   }

   In this case, the profile will not be created.

3. Email Events: If no matching identifier is found, the system sends an email to the specified address using only the data provided in the event. No additional user data is loaded, and personalization is limited to the information included in the event.

4. All Other Event Types: The event is skipped unless it falls under the categories above (Transaction, User or Email).

Matching Users with a Custom Attribute

Users can be matched using a specified custom attribute included in the JSON payload. When the attribute is specified and provided, the system will prioritize matching via the custom attribute. If the user cannot be matched with the provided custom attribute, unique identifiers will not be used as a fallback. Standard attributes are not supported for user matching.

Matching Logic Example

If an event includes both an email and mobile number, the system checks the email first. If no match is found, it then searches by mobile number. This approach ensures consistency and accuracy when identifying users across multiple data sources.

Example 1: The user profile is updated

• Event 1: The system receives an event with the email user@mapp.com.

  • Result: It creates a new user with userId 1 and email user@mapp.com.

• Event 2: The system registers another event with the same email (user@mapp.com) and, additionally, a mobile number (+1234152563).

  • Result: The existing user (userId 1) is updated to include both the email user@mapp.com and the mobile number +1234152563.

Example 2: A new user is created

• Event 3: The system receives a new event with a different mobile number (+987456321) and no email or user ID.

  • Result: The system will create a new user with userId 2 and mobile number (+987456321).

• Event 4: The system receives a new event with the same mobile number (+987456321) which belongs to userId 2 and the same email user@mapp.com which belongs to userId 1.

  • Result: In this use case, the system will not merge the profiles.

Please consider that Mapp Engage as a standard behavior does not support the merging of user profiles, and by extension this also applies to Mapp Connect.

Leveraging Custom Attributes to Match Users

Use Case Example

Scenario:
Imagine you’re managing a marketing campaign and want to unsubscribe all users associated with a specific campaign labeled as marketing-campaign: Summer2025. This attribute serves as a non-unique identifier, as multiple users can share the same campaign label.

Step-by-Step Setup:

1. Create the Contacts:
   Set up user profiles with a custom attribute marketing-campaign assigned to the appropriate value, such as Summer2025. Add these contacts to the relevant group, for instance, "Campaign Participants."

2. Configure the Mapp Connect Integration:

   • Go to the Mappings section in Mapp Connect.

   • Add the required mappings to recognize and use the custom attribute marketing-campaign as a non-unique identifier:

     • Map custom_attribute_name_with_identifier to marketing-campaign and set its type to "NONE".

     • Map marketing-campaign to marketing-campaign and set its type to "CUSTOM".

3. Perform the Action:
   Use the configured setup to send an event that unsubscribes users associated with marketing-campaign: Summer2025 from the designated group.

Example Event Payload:

{
  "unsubscribe": true,
  "custom_attribute_name_with_identifier": "marketing-campaign",
  "marketing-campaign": "Summer2025",
  "group": 1 // Replace with the actual group ID
}

Expected Result:

All users with the custom attribute marketing-campaign: Summer2025 are unsubscribed from the specified group.

Detailed Explanation of Mappings:

Custom attribute mappings are essential for this setup. The first mapping (custom_attribute_name_with_identifier) ensures the system recognizes the attribute name, while the second mapping establishes the attribute as a valid non-unique identifier for processing events. Ensure that both mappings are correctly configured in your Mapp Connect instance.

Limitation

Related Data (RD) subtype events are not user-based and cannot be used with the Related Data types unless the Related Data list is explicitly linked to a user profile. In such cases, you can use the User event type to update attributes linked to Related Data.