Tags and custom attributes

The Mapp Engage Flutter plugin supports tags and custom attributes for storing contact-related data. Both features help enrich user profiles and support segmentation, targeting, and personalized engagement flows.

Although they are often used together, tags and custom attributes serve different purposes. This guide explains when to use each one and how to manage them in Flutter.

Understand the difference between tags and custom attributes

Tags are simple string labels attached to a device or contact. They are useful for lightweight classification, such as feature membership or audience grouping.

Custom attributes store structured key-value data. They are useful when you need to save descriptive user properties such as names, account state, or preference values.

Use tags when you need simple labels. Use custom attributes when you need named fields with values.

Use tags for simple segmentation

Tags are string-based labels that can be added to or removed from the current device or resolved contact.

Examples include:

• premium_user

• beta_tester

• newsletter_subscriber

Use tags when the value is best represented as a simple label rather than a property with a defined data type.

Add, retrieve, and remove tags

Use addTag() to add a tag, getTags() to retrieve all tags, and removeTag() to remove an existing tag.

final bool added = await MappSdk.addTag('premium_user');

final List<String> tags = await MappSdk.getTags();
print('Tags: $tags');

final bool removed = await MappSdk.removeTag('premium_user');

Use custom attributes for structured profile data

Custom attributes store user-specific key-value data in Mapp Engage. Use them when you need to save named fields with explicit values.

Examples include:

• firstName

• lastName

• age

• isPremium

Custom attributes support the following value types:

• String

• int

• bool

Set custom attributes

Use setCustomAttributes() to send one or more attributes in a single call.

await MappSdk.setCustomAttributes({
  'firstName': 'Jane',
  'lastName': 'Smith',
  'age': 28,
  'isPremium': true,
});

This method accepts a single map and is the recommended way to store custom attributes in SDK v0.0.13.

Retrieve custom attributes

Use getCustomAttributes() to retrieve attribute values by key.

final Map<String, String> attrs =
    await MappSdk.getCustomAttributes(['firstName', 'age']);

print('Attributes: $attrs');

Pass a list of keys to retrieve specific attributes. If supported by your implementation, you can pass null to retrieve all available attributes.

Use the current contact context

Tags and custom attributes always operate on the currently resolved device or contact context.

This means:

• Before login, data is associated with the current anonymous device state

• After setAlias(), data is associated with the identified contact context

• After logOut(), the SDK returns to a new anonymous AUTO alias state

When your app collects profile data before user identification, decide whether that data should be re-sent after alias assignment.

Resend custom attributes after user identification

If your app stores custom attributes before the user signs in, use setAliasWithResend() when those attributes should also be associated with the identified contact.

await MappSdk.setAliasWithResend('user@example.com', true);

This is useful when the device collected profile or preference data while still operating under its anonymous AUTO alias.

Do not use deprecated typed attribute helpers

The older typed helper methods such as setAttributeString, setAttributeInt, and setAttributeBoolean are not part of SDK v0.0.13.

Use setCustomAttributes(Map) instead.

When to use tags vs. custom attributes

Use tags when you need lightweight labels for grouping or segmentation.

Use custom attributes when you need descriptive profile values with explicit field names and typed content.

Common mistakes

• Using tags for structured profile data that should be stored as custom attributes

• Using custom attributes for values that only need a simple label

• Relying on deprecated typed helper methods

• Forgetting that data is tied to the current contact context

• Skipping setAliasWithResend() when anonymous custom attributes should be associated with the identified contact

Best practices

• Use tags for simple segmentation labels

• Use custom attributes for structured contact data

• Group multiple attributes in one setCustomAttributes() call where appropriate

• Keep naming consistent across your integration

• Align attribute updates with your app's login and logout lifecycle