Tracking User Attributes

Track user attributes and manage login and logout states using the MoEngage Capacitor SDK.

MoEngage distinguishes between two types of user data:

• Identifiers — values that uniquely identify a user across devices and platforms. Use identifyUser() to set these.
• User attributes — properties you know about a user such as name, email, or plan type. Use setUserAttribute() to set these.

Identity management

For SDK versions below 6.0.0, refer to this document.

Setting identifiers is important to:

• Tie user behavior across platforms.
• Ensure unnecessary or stale users are not created.
• Identify users across installs and re-installs.

Login with a single identifier

Call the API below to pass the identifier to the MoEngage SDK.

TypeScript

import { MoECapacitorCore } from 'capacitor-moengage-core'
MoECapacitorCore.identifyUser({ identity: "identifier", appId: "YOUR_WORKSPACE_ID" })

• This method replaces the deprecated setUniqueId(). If you are using setUniqueId(), replace it with identifyUser().
• The following values are not allowed in the identifier field: unknown, guest, null, 0, 1, true, false, user_attribute_unique_id, (empty), na, n/a, "", dummy_seller_code, user_id, id, customer_id, uid, userid, none, -2, -1, 2.

Login with multiple identifiers

If your application has multiple identifiers for a user, pass all identifiers to the SDK using the API below.

TypeScript

import { MoECapacitorCore } from 'capacitor-moengage-core'
MoECapacitorCore.identifyUser({ identity: { "identifierName1": "identifierValue1", "identifierName2": "identifierValue2" }, appId: "YOUR_WORKSPACE_ID" })

Use the standard identifier keys below when passing common attributes as identifiers:

User attribute	Key
ID	uid
Email	u_em
Gender	u_gd
Birthday	u_bd
Name	u_n
First name	u_fn
Last name	u_ln
Mobile number	u_mb

For custom identifiers, use any key name that is not in the reserved keywords list.

Behavior of multiple identifyUser() calls:

• If you call identifyUser() without logging out first, the existing logged-in user’s identifiers are updated.
• If you call identifyUser() multiple times with different identifier names, the SDK appends the new identifier to the already set identifiers. Refer to the Identity resolution documentation to learn more.
• For workspaces with Identity resolution enabled, the SDK stores previous identifier values and detects changes when identifyUser() is called with new values.

Behavior change in SDK 6.0.0: The SDK no longer automatically logs out the previous user when a new user is detected. Call logoutUser() explicitly before identifying a new user to avoid data corruption.

Logout

Call this API when the user logs out of your application.

TypeScript

import { MoECapacitorCore } from 'capacitor-moengage-core'
MoECapacitorCore.logoutUser({ appId: "YOUR_WORKSPACE_ID" });

If your application registers for push tokens, pass the new push token to the MoEngage SDK after the user logs out. For more information, refer to

• Push configuration for Android
• Push configuration for iOS

Logout callback listener

Clearing user data and resetting the SDK state is an asynchronous process. Wait for the SDK to complete logout before navigating the user away or clearing your app’s local state.

Register a listener for the logoutCompleted event to detect successful logout. Wait for the callback to track any events/user attributes for the new user after the method is called.

TypeScript

import { MoECapacitorCore, MoELogoutCompleteData } from 'capacitor-moengage-core';

MoECapacitorCore.addListener("logoutCompleted", (data: MoELogoutCompleteData) => {
    console.log("Received callback 'MoELogoutComplete', data: " + JSON.stringify(data));
    // Safe to navigate to login screen or clear local app state
});

Logout callback data

TypeScript

/**
 * Data returned when a logout operation is successfully completed.
 */
export interface MoELogoutCompleteData {
  /**
   * Account information
   */
  accountMeta: MoEAccountMeta;

  /**
   * Platform type
   */
  platform: MoEPlatform;
}

Setting user attributes

You cannot use moe_ as a prefix when naming events, event attributes, or user attributes. It is a system prefix and using it may result in periodic blacklisting without prior communication.

Use the following methods to set standard user attributes such as name, email, and mobile number.

TypeScript

import { MoECapacitorCore, MoEUserGender } from 'capacitor-moengage-core'

MoECapacitorCore.setUserName({ userName: "John Doe", appId: "YOUR_WORKSPACE_ID" });

MoECapacitorCore.setFirstName({ firstName: "John", appId: "YOUR_WORKSPACE_ID" });

MoECapacitorCore.setLastName({ lastName: "Doe", appId: "YOUR_WORKSPACE_ID" });

MoECapacitorCore.setEmailId({ emailId: "[e-mail]", appId: "YOUR_WORKSPACE_ID" });

MoECapacitorCore.setMobileNumber({ mobileNumber: "1234567890", appId: "YOUR_WORKSPACE_ID" });

MoECapacitorCore.setGender({ gender: MoEUserGender.FEMALE, appId: "YOUR_WORKSPACE_ID" });

MoECapacitorCore.setBirthDate({ birthdate: "1970-01-01T12:00:00Z", appId: "YOUR_WORKSPACE_ID" });

MoECapacitorCore.setUserLocation({ location: { latitude: 25.2311, longitude: 73.1023 }, appId: "YOUR_WORKSPACE_ID" });

For custom attributes, use the generic setUserAttribute() method:

TypeScript

import { MoECapacitorCore } from 'capacitor-moengage-core'

// Generic user attribute
MoECapacitorCore.setUserAttribute({ name: "Attribute Name", value: "AttributeValue", appId: "YOUR_WORKSPACE_ID" });

// Date attribute — use ISO 8601 format
MoECapacitorCore.setUserAttributeDate({ name: "Date Attribute Name", value: "1970-01-01T12:00:00Z", appId: "YOUR_WORKSPACE_ID" });

// Location attribute
MoECapacitorCore.setUserAttributeLocation({ name: "Location Attribute Name", location: { latitude: 25.23, longitude: 73.23 }, appId: "YOUR_WORKSPACE_ID" });

Custom boolean user attribute

iOS only: Starting from version 5.x.x of capacitor-moengage-core, the default tracking format for custom boolean attributes changed from double to boolean. Use MoEAnalyticsConfig to configure this behavior.

TypeScript

import { MoECapacitorCore, MoEAnalyticsConfig, MoEInitConfig } from 'capacitor-moengage-core'

const analyticsConfig: MoEAnalyticsConfig = { shouldTrackUserAttributeBooleanAsNumber: false };
const initConfig: MoEInitConfig = { analyticsConfig: analyticsConfig };
MoECapacitorCore.initialize({ appId: "YOUR_WORKSPACE_ID", initConfig: initConfig });

TypeScript

// shouldTrackUserAttributeBooleanAsNumber: true → tracked as 1
MoECapacitorCore.setUserAttribute({ name: "Boolean Attribute True", value: true, appId: "YOUR_WORKSPACE_ID" });

// shouldTrackUserAttributeBooleanAsNumber: false → tracked as false
MoECapacitorCore.setUserAttribute({ name: "Boolean Attribute False", value: false, appId: "YOUR_WORKSPACE_ID" });

Reserved keywords

Do not use the following keys 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
• INSTALL
• UPDATE
• MOE_ISLAT
• status
• user_id
• source