|
Early Access This is an Early Access feature. To enable it for your account, contact your CSM or raise a support ticket. |
Introduction
An Object is a versatile data type that holds data in a key-value pair. An object can hold a single or multiple key-value pairs. As a marketer, you may want to segment users depending on a specific item they have added to their cart. There may be enumerable attributes that define the specified item, which can be encapsulated in a single object and can used to identify the item. For example, you want to log a list of users who added the book Atonement to their cart. The book can be defined using the following Object:
"book":{
"product_name": "Atonement"
"price" : 100,
"sku": "abc123"
}In addition to the existing data type attributes such as string, numeric, and boolean, you can use the Object data type to run deeper queries and create custom user segments for more personalized marketing campaigns.
Types of Objects
MoEngage supports the following types of objects:
Simple Object
A simple object consists of an element holding multiple key-value pairs, as shown below:
"book":{
"item-id": 123,
"item-name": "Atonement",
"item-cost": 100,
"item-currency": "USD"
}Nested Object
An object inside another object is a nested object, as shown below:
"Stationary":{
"item-id": 123,
"item-type": "books",
"item-cost": {
"amount": 100,
"currency": "USD"
}
}Array of Objects
An array of objects is a collection of elements that individually hold several key-value pairs, as shown below:
"product":[
{
"item-id": 123,
"item-type": "books",
"item-cost": 100,
"item-currency": "USD"
},
{
"item-id": 323,
"item-type": "apparel",
"item-cost": 90,
"item-currency": "USD"
},
{
"item-id": 523,
"item-type": "food",
"item-cost": 200,
"item-currency": "USD"
}
]Nomenclature Used in the Object Data Type
Consider the following object Stationary:
"Stationary":{
Level 1 "item-id": 123,
Level 1 "item-type": "books",
Level 1 "item-cost": {
Level 2 "amount": {
Level 3 "cost-price": 100,
Level 3 "discount": 0,
}
Level 2 "currency": "USD"
}
}The terms of the Object data type are described below:
| Terms | Description |
|---|---|
| Object attribute |
In the example above, Stationary is the object attribute consisting of key-value pairs or sub-attributes. The Stationary object will also be considered a root object, which can have objects nested within it. |
| Sub-attributes |
Sub-attributes are the key-value pairs inside the object attribute. In the example above: item-id, item-type, cost-price, discount, and currency are the sub-attributes or the key-value pairs. item-cost, and amount are the nested objects which have their own sub-attributes or key-value pairs. |
| Level 1 sub-attribute | Level 1 is the first level of sub-attribute nesting. |
| Level 2 sub-attribute | Level 2 is the second level of sub-attribute. |
| Level 3 sub-attribute | Level 3 is the third level of nesting. |
Key Factors for Object Data Type Ingestion
| Factors | Description |
|---|---|
| Max size of Object (bytes) |
The default size is 25 KB. Every object attribute containing key-value pairs should not exceed 25 KB. For example, an object book, as shown below, is considered an object attribute in MoEngage with multiple sub-attributes or key-value pairs: "book":{
The overall size of the object book should not exceed 25 KB. |
| Max key-value pairs (sub-attributes) |
100 sub-attributes supported inside an object attribute. You can archive unused sub-attributes within an object and ingest new sub-attributes through the Data management dashboard. "book":{
The above example has three key-value pairs or sub-attributes. |
| Max number of array elements |
By default, 50 is the maximum number of array elements. "product":[ The example above has three array elements. |
| Max level of nesting |
MoEngage supports a maximum of two levels of nesting, and anything more than that will be stringified. However, MoEngage ingests any level of nested JSON. "Stationary":{
In the example above, sub-attributes such as cost-price and discount are level 3 nested sub-attributes; they are ingested into MoEngage but in a string datatype. |
| Key names |
Max length is 200 characters. Key names should not have the following special characters: $, . , %, #. "book":{
Item-id, item-name are key names which do not exceed 200 character limit. |
| Key-values |
Max limits (default = 512 characters) follow our recommended limit for primitive data types. "book":{
Values corresponding to key names such as Item-id and item-name are called key values. Here, the key values are 123 and Atonement, which do not exceed the 512-character limit. |
| Not an identifier |
Object attributes should not be marked as primary or secondary IDs in MoEngage. Object attributes comprising sub-attributes cannot be used as a User Identifier in MoEngage to create or update new users. Primitive data type attributes (for example, CustomerID in string datatype) need to be used. |
| No logical operation |
Object data types do not support logical operations. Perform such operations on Object.child (if it is of primitive type). "book":{
In the previous example of an object attribute book, logical operations can be performed against the sub-attributes inside the book object but not on the book as a complete object. For example, A logical operation that can be considered valid is book.item-cost < 150. |
| PII or masked or blocked or hide |
The entire object attribute can be marked PII or encrypted. Sub-attributes or individual key-value pairs inside an object cannot be marked as PII, encrypted, blocked, or hidden separately. |
| Max Object-type Attributes |
By default, MoEngage allows a maximum of five attributes (user or events) as Object data types. That is, five user attribute objects and five event attribute objects totaling 10 object attributes. |
| Custom attributes only (both User and Event) |
Only custom attributes can be an Object data type. Attempting to send an Object data type on standard attributes will not be accepted. Standard or derived attributes are data attributes that MoEngage tracks through the MoEngage SDK. You can find these attributes at Settings > Analytics and Data > Data management in the MoEngage dashboard. These attributes are not Object data types. |
| Null handling |
If the incoming Object type attribute is Null or empty, it is not ingested into MoEngage. If an object consists of an attribute that has no values among other attributes which have value, that object is partially ingested whereas the attribute with blank/null value is not ingested: "product":[ Data ingested into MoEngage is as shown below: "product":[ |
Ingest Object Data Type
This section describes how you can ingest the Object data type into MoEngage.
S2S API
curl --location 'https://api-xx.moengage.com/v1/transition?app_id=O7NIHY0AT1K1FL8DR1J1G' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{Authorization_Key}}' \
--data-raw '{
"type": "transition",
"elements": [
{
"type": "customer",
"customer_id": "tONX83z_new",
"attributes": {
"name": "xQEC",
"first_name": "",
"last_name": "",
"age": "70",
"email": "Ra4X@xyz. Com",
"gender": "female",
"mobile": "238706106351",
"geo": "88.90 89.00",
"birthday": "02-12-2001",
"created_time": "1716372929998",
"last_seen": "1716372929998",
"source": "FBsuS",
"object_with_nesting_user_attribute_01": {
"item-id": 123,
"item-type": "books",
"item-cost": {
"amount": 100,
"currency": "USD"
}
},
"array_of_object_sample_user_attribute_01": [
{
"item-id": 123,
"item-type": "books",
"item-cost": 100,
"item-currency": "USD"
},
{
"item-id": 323,
"item-type": "apparel",
"item-cost": 90,
"item-currency": "USD"
},
{
"item-id": 523,
"item-type": "food",
"item-cost": 200,
"item-currency": "USD"
}
],
"platforms": [
{
"platform": "ANDROID",
"active": "true"
}
]
}
},
{
"type": "event",
"customer_id": "tONX83z",
"actions": [
{
"action": "object_event_s2s_ios_level1",
"attributes": {
"object_with_nesting_event_attribute_01": {
"item-id": 123,
"item-type": "books",
"item-cost_event_attribute": {
"amount": 100,
"currency": "USD"
}
},
"array_of_object_sample_event_attribute_01": [
{
"item-id": 123,
"item-type": "books",
"item-cost": 100,
"item-currency": "USD"
},
{
"item-id": 323,
"item-type": "apparel",
"item-cost": 90,
"item-currency": "USD"
},
{
"item-id": 523,
"item-type": "food",
"item-cost": 200,
"item-currency": "USD"
}
]
},
"platform": "",
"app_version": "3019",
"user_time": "1716372929998",
"current_time": "1716372929998"
}
]
}
]
}'SDK
curl --location 'endpoint' \
--header 'Content-Type: application/json' \
--header 'MOE-APPKEY: {{Workspace_ID or APP_ID}}' \
--data-raw '{
"viewsInfo": [
{
"EVENT_ACTION": "EVENT_ACTION_USER_ATTRIBUTE",
"EVENT_ATTRS": {
"USER_ATTRIBUTE_UNIQUE_ID": "123"
},
"EVENT_L_TIME": "22:05:2024:14:02:01",
"EVENT_G_TIME": "1716372930"
},
{
"EVENT_ACTION": "EVENT_ACTION_USER_ATTRIBUTE",
"EVENT_ATTRS": {
"USER_ATTRIBUTE_USER_NAME": "xQEC"
},
"EVENT_L_TIME": "22:05:2024:14:02:01",
"EVENT_G_TIME": "1716372930"
},
{
"EVENT_ACTION": "EVENT_ACTION_USER_ATTRIBUTE",
"EVENT_ATTRS": {
"USER_ATTRIBUTE_USER_FIRST_NAME": "JgfOr"
},
"EVENT_L_TIME": "22:05:2024:14:02:01",
"EVENT_G_TIME": "1716372930"
},
{
"EVENT_ACTION": "EVENT_ACTION_USER_ATTRIBUTE",
"EVENT_ATTRS": {
"USER_ATTRIBUTE_USER_EMAIL": "Ra4X@xyz. Com"
},
"EVENT_L_TIME": "22:05:2024:14:02:01",
"EVENT_G_TIME": "1716372930"
},
{
"EVENT_ACTION": "EVENT_ACTION_USER_ATTRIBUTE",
"EVENT_ATTRS": {
"USER_ATTRIBUTE_USER_LOCATION": "104.248,122.203"
},
"EVENT_L_TIME": "22:05:2024:14:02:01",
"EVENT_G_TIME": "1716372930"
},
{
"EVENT_ACTION": "EVENT_ACTION_USER_ATTRIBUTE",
"EVENT_ATTRS": {
"object_with_nesting_user_attribute_001": {
"item-id": 123,
"item-type": "books",
"item-cost_0001": {
"amount": 100,
"currency": "USD"
}
},
"array_of_object_sample_user_attribute_002": [
{
"item-id": 123,
"item-type": "books",
"item-cost": 100,
"item-currency": "USD"
},
{
"item-id": 323,
"item-type": "apparel",
"item-cost": 90,
"item-currency": "USD"
},
{
"item-id": 523,
"item-type": "food",
"item-cost": 200,
"item-currency": "USD"
}
]
},
"EVENT_L_TIME": "22:05:2024:14:02:01",
"EVENT_G_TIME": "1716372930"
},
{
"EVENT_ACTION": "object_event_reports_ios_level1",
"EVENT_ATTRS": {
"object_with_nesting_user_attribute_003": {
"item-id": 123,
"item-type": "books",
"item-cost": {
"amount": 100,
"currency": "USD"
}
},
"array_of_object_sample_user_attribute_004": [
{
"item-id": 123,
"item-type": "books",
"item-cost": 100,
"item-currency": "USD"
},
{
"item-id": 323,
"item-type": "apparel",
"item-cost": 90,
"item-currency": "USD"
},
{
"item-id": 523,
"item-type": "food",
"item-cost": 200,
"item-currency": "USD"
}
]
},
"EVENT_L_TIME": "22:05:2024:14:02:01",
"EVENT_G_TIME": "1716372930"
}
],
"viewsCount": 3,
"identifiers": {}
}'Snowflake
The Object data type is supported in Snowflake as well.
Store Compatible JSON Data in Snowflake
To store valid JSON inside Snowflake, you must change the data type of the column to VARIANT type. For more information, refer here.
The JSON stored inside Snowflake should be a valid JSON; otherwise, the values will not be written as JSON. Here is an example JSON column:
{ "Designation": "SSE", "Palace": "Banglore", "age": 30, "name": "Shasha" }Import JSON Data via Snowflake
Existing attributes in MoEngage that have been marked as an Object type and are available to map to columns in Snowflake:
You can always create new Object attributes from the mapping step as well, as shown below:
| info |
Information MoEngage does not support mapping with nested attributes. Only top-level attributes are available to map. |
Zapier
Zapier now supports creating users and events with object-type attributes. To mark an attribute as an object type, you need to define these attributes inside the Object-type Attributes list:
Any attribute with an invalid JSON value is dropped. The same flow applies to the Import User Event Action.
| info |
Information Any attributes that are intended to be Object type but are defined under the Custom Attributes list are sent to MoEngage as strings. Here, the default type casting conversion rules of MoEngage are applied based on the attribute’s pinned data type. |
Exceptions
- Only five objects can be ingested for each workspace by default.
- Elements inside an object or in an array_objects are dropped if nulls or blanks exist.
|
|
Sample Payload | MoEngage Behavior |
|---|---|---|
| 1 | attribute0 : {} | Dropped |
| 2 | attribute01 : { } | Dropped |
| 3 | Attribute61 : [{ "a" : {} }, {"valid" : false}] | [{"valid": false}] is ingested, rest of the elements are dropped |
| 4 | {"": "value" } | Dropped |
- A heterogeneous array of objects is not supported. An array of objects should only consist of objects as the array elements.
- Case 1: If there is a mix of objects and primitive elements, primitive elements are dropped.
- Case 2: If there are no objects in the array but the array consists of other primitive elements, MoEngage takes the first element’s datatype as the reference datatype and attempts to typecast the rest of the elements into that datatype. If this attempt is unsuccessful, the elements are dropped.
Use Object Data Type
This section describes how to use the Object data type.
Data Management
After ingesting your Object data type attributes in MoEngage, you can manage them in the Data management section of the MoEngage dashboard. To edit an Object data type, follow the steps below:
- Navigate to your MoEngage dashboard and click Settings > Analytics and Data > Data management > User attributes or Events.
- Select the user attribute of the Object data type or search for one using the search bar.
- Click the vertical ellipsis on the attribute row and click Edit.
- Modify your Object structure. For example, change the string attribute to boolean, numeric to string, and so on.
- Click Save. A warning is displayed on saving the modifications.
- Click Continue to confirm.
info Information
You can edit the Object attribute once every 24 hours. For the same reason, the edit option will only be activated 24 hours following the current edit.
Activities Allowed on Object Attributes in Data Management
- You can pin data type as Object or Array of Object for any custom user or event attribute.
- For any Object or Array of Object data type, the system auto-detects the object's structure and saves it as metadata for segmentation.
- The structure detected must have all children of the Object and their data type up to two levels.
- You can manually define each child node for any Object or Array of Object type attribute.
- If the schema of an Object attribute is defined manually, it cannot be modified for 24 hours (to avoid unwanted issues with any running campaigns/triggers). After the schema is manually defined, any incoming data is validated against it and rejected if it does not conform to the definition.
- For any Object or Array of the Object type attribute, you can paste a sample JSON to generate a defined Object structure.
- You can specify the data type of each child node up to two levels. The data types supported are as follows:
- Numeric
- Boolean
- String
- Date type
- Primitive Array
- JSON (to ingest any level of nested object)
- You can create more than 100 children nodes for any object definition. If an object has more than 100 children nodes, MoEngage accepts only the first 100 children nodes defined earlier.
- If an existing attribute is pinned as an object, the previous values are not type-casted and left as they are.
- New values coming in for the attribute are treated differently for different scenarios as follows:
- If the incoming value is an object under defined limits, it will be accepted.
- If the incoming value is a primitive data type (number, string, bool), it is encapsulated and typecasted as an object.
- You can change the data type of an attribute pinned as an object to “Any” or any of the primitive data types.
- You can change Block/Unblock and Show/Hide sub-attributes of the Object data type for only root-level attributes.
- You can edit the schema of Object data type attributes in the following manner:
- Add new sub-attributes to the object for up to two levels of nesting.
- Delete existing sub-attributes.
Exceptions
- An attribute can ingest data as an object or as any primitive data type.
- Any attribute that has ingested any data point of the object data type cannot be encrypted.
- Any attribute that has been ingesting data in any primitive data type and marked as PII encrypted attribute cannot ingest object data points going forward.
User Profile
This section describes the user profile.
User Info
After you ingest your Object data type attributes in MoEngage, you can view them in the User Profile section on your MoEngage dashboard. To view the Object attribute, follow the steps below:
- Navigate to your MoEngage dashboard and create a Segment with object attributes.
- On the Create segment page, scroll down to the Query Results section and then select a query.
- Select a sample user to navigate to the User Profile page. Alternatively, use the upper right search bar to search for a user with an ID.
- You can view all your object-type attributes on the User Profile page under the Tracked Custom Attributes section.
Activity Info
To view the object attribute associated with an event in activity info, follow the steps below:
- Navigate to your MoEngage dashboard and create a Segment with Object attributes.
- On the Create segment page, scroll down to the Query Results section and then click a query to expand it.
- Select a sample user to navigate to the User Profile page. Or search for a user (using user ID) in the user search box on the upper right corner of the Create segment page.
- From the User Profile page, go to the Activity Info tab, where you can view all your events and event attributes in the object type section.
Object Data Type Support in Campaigns and Channels
The table below mentions the delivery type and indicates whether or not the object data type is supported across different campaigns.
| Campaign Type | Push | SMS | Connector | ||
|---|---|---|---|---|---|
| One Time | Yes | Yes | Yes | Yes | Yes |
| Periodic | Yes | Yes | Yes | Yes | Yes |
| Event Triggered | Yes | Yes | Yes | Yes | Yes |
| Business Event Triggered | No | No | No | NA* | NA* |
| Device Triggered | No | NA* | NA* | NA* | NA* |
| Location Triggered | Yes | NA* | NA* | NA* | NA* |
NA* indicates that the delivery type is not supported for that particular campaign.
The table below mentions the channels and indicates whether the object data type is supported.
| Channels | In-app | Onsite | Cards | Google Ads | Web Personalization | |
|---|---|---|---|---|---|---|
| Object data type supported or not | Yes | Yes | No | No | No | Yes |
The table below outlines the steps involved in campaign creation and indicates whether the object data type is supported across different campaigns.
| Campaign Creation Steps | Object Data Type Supported? |
|---|---|
| Target Users > Select audience > All users, Filter users by > User property, User behavior | Yes |
| Content > Link personalization, Image personalization, preview | Yes |
| Content > Add new locale > User Property | No |
| Schedule and goals > Conversion goals > New goal > Select an event | No |
The table below outlines the steps involved in Flow creation and indicates whether the object data type is supported across different campaigns.
| Flow creation steps | Object Data Type Supported? |
|---|---|
| When will users enter the flow > On event trigger > IF user has executed > Select an event | Yes |
| When will users enter the flow > On flow exit > When user has exited > Select by name | Yes |
| Who will enter the flow > Audience > All users, Filter users by> User property, User behavior | Yes |