User attributes are pieces of information you know about a user. They could be demographics such as age and gender, account-specific like plan, or whether a user has seen a particular A/B test variation. User attributes are customer properties you can reference throughout the customer's lifecycle.

Difference Between User Attributes and User Identifiers

User attributes and user identifiers serve different purposes in MoEngage: 

User Identifiers:

User identifiers are unique values that persist across multiple sessions and devices, allowing MoEngage to recognise a user as the same individual, even when they switch between different platforms or log in later. This process, known as identity resolution, is crucial for maintaining a unified user profile, providing a consistent user experience, and tracking user behaviour accurately.

Common examples of user identifiers include:

• Email address: A user's email address is a widely used identifier because it is unique to the individual and remains consistent across different platforms.
• Phone number: Similar to email addresses, phone numbers can serve as unique identifiers, especially in mobile applications.
• User ID: MoEngage assigns each user a unique ID upon registration. This ID is used as a reliable identifier within the MoEngage platform.
• Customer ID: In e-commerce and customer relationship management (CRM) systems, a customer ID is assigned to track individual customers across various interactions.

These identifiers are set using the identifyUser() method.

By default, parameter ID is the identifier used for your workspaces, unless Identity resolution is enabled and identifiers are activated in your workspace.

User Attributes:

Descriptive information about a user that enhances their profile - Used for segmentation, personalisation, and analytics - Examples: name, age, gender, preferences, purchase history - Set using dedicated methods like setFirstName() or setUserAttribute() - Help create personalised user experiences 

In simple terms, identifiers answer "Who is this user?" while attributes answer "What do we know about this user?"

Powering MoEngage Features

User attributes and identifiers are crucial for leveraging MoEngage effectively:

• Segmentation:
  • Use attributes to create targeted user groups based on demographics, behavior, etc.
  • Example: Segment users by age, purchase history for specific campaigns.
• Personalisation:
  • Identifiers ensure consistent user experience across devices.
  • Attributes enable tailored content (messages, recommendations).
  • Example: Personalise emails with names, recommend relevant products.
• Analytics:
  • Attributes provide context to user actions and behavior data.
  • Analyze conversion rates by segments, feature engagement by demographics.
  • Gain deeper insights for data-driven decisions.

By using attributes and identifiers, you can build more relevant and engaging user experiences.

Implementing Login/Logout

For SDK versions below 9.2.00 refer to this document.

Login User

Single Identifier

If your application relies on a single unique user identifier, such as an email ID for login, use the API below to pass the identifier to the MoEngage SDK

import 'package:moengage_flutter/moengage_flutter.dart';
final MoEngageFlutter _moengagePlugin = MoEngageFlutter();
_moengagePlugin.initialise();

_moengagePlugin.identifyUser("flutter-uid"); //Pass any unique value for your user

Multiple Identifiers

If your application supports multiple login identifiers, such as an email ID, user ID, or mobile number, pass all relevant identifiers to the SDK using the following function:

import 'package:moengage_flutter/moengage_flutter.dart';
final MoEngageFlutter _moengagePlugin = MoEngageFlutter();
_moengagePlugin.initialise();
_moengagePlugin.identifyUser({"email": "flutter@moengage.com", "id": "flutter"});

Note: Before implementing identifyUser() with multiple identifiers, you must activate the defined identifiers on the MoEngage dashboard. For configuration steps, see this documentation.

Behaviour of Multiple identifyUser() calls

• When calling identifyUser() multiple times, the new identifiers are appended to the existing list rather than replacing them. Here's an example of how this works:
  
  Dart

  import 'package:moengage_flutter/moengage_flutter.dart';
  final MoEngageFlutter _moengagePlugin = MoEngageFlutter();
  _moengagePlugin.initialise();
  //First call with email _moengagePlugin.identifyUser({"u_em": "flutter@moengage.com"});
  //Later call identifyUser() with mobile Number
  _moengagePlugin.identifyUser({"u_mb":"999999999"});
  
  //Result now the user has both email and mobile identifiers;

• If you call identifyUser() with an identifier key that already exists, the new value will be update the existing one. Here's an example of how this works:
  
  Dart

  import 'package:moengage_flutter/moengage_flutter.dart';
  final MoEngageFlutter _moengagePlugin = MoEngageFlutter();
  _moengagePlugin.initialise();
  //First call with initial email _moengagePlugin.identifyUser({"u_em":"abc@xyz.com"});
  //Later call identifyUser() when User updates their email
  _moengagePlugin.identifyUser({"u_em":"jfk@xyz.com"});
  //Result now the user email is updated with the later one;

This behaviour allows you to:

• Add new identifiers as they become available
• Update specific identifiers without affecting others
• Build a complete user identity profile over time

Here, u_em, u_mb are standard user attributes. Please refer to this section to identify user with more standard user attributes

Standard and Custom Attributes

Standard attributes: These are common user attributes that are pre-defined within the MoEngage dashboard, such as email address and mobile phone number. The table below lists these standard attributes and their corresponding key names

Custom attributes:  These are attributes that you define yourself within the MoEngage dashboard in addition to the standard attributes. Here's an example of how you might work with custom attributes:

import 'package:moengage_flutter/moengage_flutter.dart';
final MoEngageFlutter _moengagePlugin = MoEngageFlutter(<YOUR_WORKSPACE_ID>);
_moengagePlugin.initialise();

//replace custom_attribute_name with the actual name of your custom user attribute and attributeValue with the actual value you want to assign to the attribute
_moengagePlugin.identifyUser({ custom_attribute_name: 'attributeValue' });
      
//you can set two or more identities at the same time
_moengagePlugin.identifyUser({ cust_attr_1: 'value1', cust_attr_2: 'value2' });
      
//you can set custom user identity and standard user identity at the same time
_moengagePlugin.identifyUser({ cust_attr_1: 'value1', cust_attr_2: 'value2', u_em: 'emailValue@emailDomain.com' });

For detailed instructions on selecting both custom and standard attributes when configuring multiple identifiers, please refer to this document.

Logout User

The application needs to notify the MoEngage SDK whenever the user is logged out of the application. To notify the SDK, call the API whenever the user is logged out of the application.

import 'package:moengage_flutter/moengage_flutter.dart';
final MoEngageFlutter _moengagePlugin = MoEngageFlutter(YOUR_WORKSPACE_ID);
_moengagePlugin.initialise();
_moengagePlugin.logout();

Tracking User Attributes

Use the following helper methods to set User attributes like Name, Email, Mobile, Gender, etc.

import 'package:moengage_flutter/moengage_flutter.dart';
final MoEngageFlutter _moengagePlugin = MoEngageFlutter(YOUR_WORKSPACE_ID);
_moengagePlugin.initialise();

_moengagePlugin.setUserName("User Name");
_moengagePlugin.setFirstName("FirstName");
_moengagePlugin.setLastName("LastName");
_moengagePlugin.setEmail("EmailID");
_moengagePlugin.setPhoneNumber("PhoneNumber");
_moengagePlugin.setGender(MoEGender.male); // Supported values also include MoEGender.female OR MoEGender.other
_moengagePlugin.setLocation(new MoEGeoLocation(23.1, 21.2)); // Pass coordinates with MoEGeoLocation instance
_moengagePlugin.setBirthDate("2000-12-02T08:26:21.170Z"); // date format - ` yyyy-MM-dd'T'HH:mm:ss.fff'Z'`

For setting other User Attributes, you can use the generic method setUserAttribute(key,value)

To set custom user attributes, you will have to provide the attribute name as shown below:

import 'package:moengage_flutter/moengage_flutter.dart';
final MoEngageFlutter _moengagePlugin = MoEngageFlutter(YOUR_WORKSPACE_ID);
_moengagePlugin.initialise();

_moengagePlugin.setUserAttribute("int-attr", 0);
_moengagePlugin.setUserAttribute("bool-attr", true);
_moengagePlugin.setUserAttribute("string-attr", "Some Value");
_moengagePlugin.setUserAttribute("double-attr", 10.0);
_moengagePlugin.setUserAttribute("int-arr-attr", [100,200,300]);
_moengagePlugin.setUserAttribute("string-arr-attr", ["a","b","c"]);
_moengagePlugin.setUserAttribute("double-arr-attr", [1.0,2.0,3.0]);
_moengagePlugin.setUserAttribute('product', {'item-id' : 123,'item-type' : 'books','item-cost' : {'amount' : 100,'currency' : 'USD'}});
_moengagePlugin.setUserAttribute('products', [{'item-id' : 123,'item-cost' : {'amount' : 100,'currency' : 'USD'}},{'item-id' : 323,'item-cost' : {'amount' : 90,'currency' : 'USD'}}]);

Tracking Date as user attributes:

To track any date as user attributes use the setUserAttributeIsoDate(name, date). This API takes the attribute name and ISO Date as input.
Date Format - yyyy-MM-dd'T'HH:mm:ss.fff'Z'
Example:

import 'package:moengage_flutter/moengage_flutter.dart';
final MoEngageFlutter _moengagePlugin = MoEngageFlutter(YOUR_WORKSPACE_ID);
_moengagePlugin.initialise();
_moengagePlugin.setUserAttributeIsoDate("timeStamp", "2019-12-02T08:26:21.170Z")

Tracking Location as user attributes: (Not available for Web)

To track any location as user attributes use the setUserAttributeLocation(). This API takes the attribute name and an instance of MoEGeoLocation for coordinates as input.
Example:

import 'package:moengage_flutter/moengage_flutter.dart';
final MoEngageFlutter _moengagePlugin = MoEngageFlutter(YOUR_WORKSPACE_ID);
_moengagePlugin.initialise();
_moengagePlugin.setUserAttributeLocation("locationAttr", new MoEGeoLocation(72.8, 53.2));

Custom Boolean User Attribute

iOS (optional)

Starting from version 8.x.x of moengage_flutter, the default tracking for the custom boolean attribute will be changed to boolean(true/false) from double(0/1). To configure this, use AnalyticsConfig with shouldTrackUserAttributeBooleanAsNumber and pass true to track the boolean as double. By default, this is set as false to track boolean as true/false.

Refer to the example below

 import 'package:moengage_flutter/moengage_flutter.dart';

final MoEngageFlutter _moengagePlugin = MoEngageFlutter(YOUR_Workspace_ID, moEInitConfig: MoEInitConfig(analyticsConfig: AnalyticsConfig(shouldTrackUserAttributeBooleanAsNumber:true)));

@override
void initState() {
super.initState();
initPlatformState();
_moengagePlugin.initialise();
}

Refer to the example code below for tracking the boolean user attribute 

 import 'package:moengage_flutter/moengage_flutter.dart';

final MoEngageFlutter _moengagePlugin = MoEngageFlutter(YOUR_Workspace_ID, moEInitConfig: MoEInitConfig(analyticsConfig: AnalyticsConfig(shouldTrackUserAttributeBooleanAsNumber: false)));
_moengagePlugin.initialise();

// If shouldTrackUserAttributeBooleanAsNumber is passed as true then `bool-attr-false` will tracked with value 0 else false
_moengagePlugin.setUserAttribute("bool-attr-false", false);

// If shouldTrackUserAttributeBooleanAsNumber is passed as true then `bool-attr-true` will tracked with value 1 else true
_moengagePlugin.setUserAttribute("bool-attr-true", true);

Reserved keywords for User Attributes

Below is the list of keys that should not be used when tracking user attributes.

• USER_ATTRIBUTE_UNIQUE_ID
• USER_ATTRIBUTE_USER_EMAIL
• USER_ATTRIBUTE_USER_MOBILE
• USER_ATTRIBUTE_USER_NAME
• USER_ATTRIBUTE_USER_GENDER
• USER_ATTRIBUTE_USER_FIRST_NAME
• USER_ATTRIBUTE_USER_LAST_NAME
• USER_ATTRIBUTE_USER_BDAY
• USER_ATTRIBUTE_NOTIFICATION_PREF
• USER_ATTRIBUTE_OLD_ID
• MOE_TIME_FORMAT
• MOE_TIME_TIMEZONE
• USER_ATTRIBUTE_DND_START_TIME
• USER_ATTRIBUTE_DND_END_TIME
• MOE_GAID
• MOE_ISLAT
• status
• user_id