Skip to main content

Documentation Index

Fetch the complete documentation index at: https://moengage-crashes-in-debug-feedback.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

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

​
Identifying Users

For SDK versions below 9.23.0 refer to this document. Setting identifiers is important to:
  • To tie user behavior across platforms, i.e., iOS, Android, Web, etc.
  • This is to ensure unnecessary or stale users are not created.
  • To identify users across installs/re-installs.

​
Single Identifier

Call the API below to pass the identifier on to the MoEngage SDK. 
MoEngageSDKAnalytics.sharedInstance.identifyUser(identity: "identifier")
This method is a replacement for the deprecated setUniqueId(). If you are using ***setUniqueId() ***in your application, consider replacing it with identifyUser()**.

​
Multiple Identifiers

If your application has multiple identifiers using which you identify a user you can pass all the identifiers to the SDK using the below API. 
MoEngageSDKAnalytics.sharedInstance.identifyUser(
    identities: [
        "identifierName1": "identifierValue1", "identifierName2" to "identifierValue2"
    ]
)
If you call identifyUser() multiple times with different identifier names, the SDK will append this identifier to the already set identifiers.
InformationUpdates are made to SDK functions to improve user identification and session management.
  • Forced Logout: The MoEngage SDK no longer automatically logs out the previous user when a new user is detected on the device. Logout should now be explicitly called for workspaces enabled with Identity resolution to avoid data corruption.
  • SetUniqueID: IdentifyUser function supports multiple identifiers, which replaces the need of using SetUniqueID function for user identification. Note that SetUniqueID is marked for removal in the future releases of SDK versions - it is important to use identifyUser instead especially if you are using Identity resolution in your workspace.
  • SetAlias: For workspaces with the Identity resolution feature enabled, MoEngage SDK stores the previous identifier values. When IdentifyUser function is used to track the new identifier values, MoEngage SDK detects the change in identifier value and reports accordingly.
  • If you call the IdentifyUser function without logging out, then the existing logged-in user’s ID is updated.
Refer to our help document to learn more about the feature.

​
Logout

The application needs to notify the MoEngage SDK whenever the user is logged out of the application. Call the API whenever the user is logged out of the application to notify the SDK. 
MoEngageSDKAnalytics.sharedInstance.resetUser()

​
Default User Attributes

Some default SDK User Attribute can be set for eg. email-id, mobile number, gender, user name, birthday. The default attributes tracked by SDK can be set as shown below: 
MoEngageSDKAnalytics.sharedInstance.setName(userName)
MoEngageSDKAnalytics.sharedInstance.setLastName(userLastname)
MoEngageSDKAnalytics.sharedInstance.setFirstName(userFirstName)
MoEngageSDKAnalytics.sharedInstance.setEmailID(userEmailID)
MoEngageSDKAnalytics.sharedInstance.setMobileNumber(userPhoneNo)
MoEngageSDKAnalytics.sharedInstance.setGender(.male) //Use UserGender enumerator for this
MoEngageSDKAnalytics.sharedInstance.setDateOfBirth(userBirthdate)//userBirthdate should be a Date instance
MoEngageSDKAnalytics.sharedInstance.setLocation(MoEngageGeoLocation(withLatitude: userLocationLat, andLongitude: userLocationLng)) //userLocationLat and userLocationLng are double values of the location coordinates
  • User Phone No / Mobile Number must be tracked as a string to work properly in MoEngage systems.
  • For more information on supported data types and data tracking policies, refer to Data Tracking Policies.
For the full list of validation rules and what happens in DEBUG versus release builds, refer to Validations and restrictions.

​
Custom User Attributes

To set custom attributes just provide custom keys different to the ones present in here. Following is an example: 
MoEngageSDKAnalytics.sharedInstance.setUserAttribute("Bengaluru", withAttributeName: "Current_city")
MoEngageSDKAnalytics.sharedInstance.setUserAttribute(["Bengaluru","Delhi","Chennai"], withAttributeName: "Current_cities")
For the full list of validation rules, refer to Validations and restrictions.

​
JSON Attributes

From MoEngage-iOS-SDK v9.17.5, we have added support for JSON and array of JSON user attributes. Following is an example: 
MoEngageSDKAnalytics.sharedInstance.setUserAttribute(["item-id" : 123,"item-type" : "books","item-cost" : ["amount" : 100,"currency" : "USD"]],withAttributeName: "product")

MoEngageSDKAnalytics.sharedInstance.setUserAttribute([["item-id" : 123,"item-cost" : ["amount" : 100,"currency" : "USD"]],["item-id" : 323,"item-cost" : ["amount" : 90,"currency" : "USD"]]],withAttributeName: "products")

​
Date and Time User Attributes

Date and time attributes can be set as user attributes. For this refer to the methods in the code block below: 
//1. Track UserAttribute using Date instance
MoEngageSDKAnalytics.sharedInstance.setUserAttributeDate(Date(), withAttributeName: "Date Attr 1")

//2. Track UserAttribute using ISO Date String in format "yyyy-MM-dd'T'HH:mm:ss'Z'"
MoEngageSDKAnalytics.sharedInstance.setUserAttributeISODate("2020-01-12T18:45:59Z", withAttributeName: "Date Attr 2")

//3. Track UserAttribute using Epoch value
MoEngageSDKAnalytics.sharedInstance.setUserAttributeEpochTime(663333, withAttributeName: "Date Attr 3")

​
Location Attributes

The location of a user or any location can be set as user attribute. For this use setLocation(_:withAttributeName:) method and pass lat, the long value of the location as shown in the following example: 
MoEngageSDKAnalytics.sharedInstance.setLocation(MoEngageGeoLocation.init(withLatitude: 72.90909, andLongitude: 12.34567), withAttributeName: "attribute name")

​
Validations and restrictions

User attributes have two layers of validation that apply across both DEBUG and release builds:
  • Naming and format rules — these always apply, regardless of build configuration.
  • Type validation — invalid attribute values cause a fatal exception in DEBUG builds and are silently dropped in release builds.
In the iOS SDK, DEBUG mode means the SDK was initialized using initializeDefaultTestInstance(_:) (TEST workspace) and the app is running attached to Xcode. This is different from a release build that has debug symbols enabled.

​
Naming and format rules

  • Attribute names must be non-empty. Passing an empty string ("") as an attribute name causes a fatal exception in DEBUG builds. In release builds, the attribute is dropped.
  • No dot (.) in attribute names.
  • Attribute names must not start with a dollar sign ($).
  • Reserved prefix. You cannot use moe_ as a prefix when naming events, event attributes, or user attributes. It is a system prefix, and using it might result in periodic blocklisting without prior communication.
  • Reserved keywords. Do not use any of the following keys when tracking user attributes — they are reserved for SDK and system use:
    • 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
    • USER_ATTRIBUTE_DND_START_TIME
    • USER_ATTRIBUTE_DND_END_TIME
    • MOE_TIME_FORMAT
    • MOE_TIME_TIMEZONE
    • MOE_GAID
    • MOE_ISLAT
    • INSTALL
    • UPDATE
    • status
    • user_id

​
Supported attribute value types

Attribute values must be one of: String, Number, Date, MoEngageGeoLocation, Dictionary, or Array (of strings or numbers). NSURL is not supported — convert to a string before passing it. If an unsupported value is passed:
  • In DEBUG builds, the SDK throws a fatal exception and crashes the app so you can catch data issues early.
  • In release builds, the SDK drops the specific invalid attribute. Other attributes set on the user are unaffected.
Common triggers for the DEBUG exception:
  • Passing null (NSNull()).
  • Passing custom models or UI elements (for example, UIColor, UIImage).
  • Passing invalid numbers like NaN or Infinity.
  • Passing empty Arrays or Dictionaries.
  • Nesting Date or MoEngageGeoLocation objects inside an Array or Dictionary. These must be passed directly as values.