Components of IDSync

There are five key components to IDSync: Identity Records, The Identity API, Identity Scopes, Order of Identities, and Identity Strategy.

Identity Records

Behind the scenes, mParticle maintains a User Profile for each user. You can think of a User Profile as a big folder of data: events, user attributes, identities, attribution info, device info. User Profiles are used to drive the Audience Builder and to enrich incoming data with all relevant information about a user before forwarding it to an Output service. The main purpose of IDSync is to assign incoming data to the correct User Profile. However, to identify users in real time, IDSync doesn’t look at the entire User Profile, but at that Profile’s Identity Record. Think of the Identity Record as a label on the front of your folder of data. The Identity Record contains a list of all identities that can currently be used to ”look up” that folder. Identity Records have a 1:1 relationship with User Profiles. Anytime a new User Profile is created, a matching Identity Record is also created. Some key things to note about User Profiles vs. Identity Records:

• Some uses of IDSync force identities to be unique to a single Identity Record. Email Addresses are a good example. See Unique Identities for more information.
• The Identity Record might not contain every possible type of Identifier available in a User Profile, but only the types you have specified in your Identity Priority.

Identity API

The Identity API is used by all of mParticle’s SDKs to log users in and out of your app and to modify a current user’s identities. It is also available as an HTTP API.

Identify a User

The Identity API provide 3 endpoints for identifying users:

• Identify - called when a session begins with whatever identifying information is available
• Login - called when a known user signs into the app.
• Logout - called when a known user signs out

These three endpoints are called in response to different user actions, but they all perform the same function - resolving a request containing all known identifying information for the current user into a single, unique mParticle User Profile. That profile might be:

• An existing profile that matches all identifying information in the request
• An existing profile that matched some identifying information in the request, updated to include new information.
• A new user profile, created when no existing profiles matched the request.

Modify a User

A Modify request is different from an Identity Request, in that it must include the unique mParticle ID for the current user and never returns a new mParticle ID. Instead, it instructs mParticle to update the current user’s identities based on the identifying information in the request. For example, a modify request might be used to update a user’s email address.

When an Identity request is received, mParticle determines how to respond to the request by referring to your chosen Identity Strategy.

Identity Scope

mParticle data is organized in three tiers: Organization → Account → Workspace. Identity Scope determines how user data is shared between workspaces and accounts under an Organization. An Identity Scope is a set of user data in which each user profile and each ’known user’ identity is required to be unique. Multiple accounts or workspaces under an mParticle Organization can share the same Identity Scope, but a workspace cannot be connected to more than one Identity Scope. For some use cases, it might be beneficial for an Organization to maintain more than one Identity Scope. For example:

• Food delivery apps have both customers and couriers as users of their app ecosystem, but analytics requirements for each group are very different. Additionally, a courier may also use the app as a customer. Storing the data from both roles against the same profile could create confusion. By creating a separate Identity Scope for each set of users, data is kept clean and relevant.
• Large enterprise organization may not yet have a consistent way of identifying users across branches and subsidiaries. Creating separate Identity Scopes allow pools of differently identified users to be kept separate.
• Businesses that operate internationally may need to separate their customers geographically to comply with local laws.
• Multi-sided organisations, such as social media organizations, may conduct separate B2C and B2B business. For example, a user of a social media app may use the same login to post personal status updates and also to purchase advertising. Multiple Identity Scopes allow these activities to be considered separately.

Identity Priority

An Identity Strategy must define order of precedence for matching user profiles. When an identity request is received, mParticle will lookup matching profiles for each identifier in the order defined by the Identity Priority until a single profile can be returned. Keep in mind that some Identity Strategies impose minimum requirements that a request must fulfil in order to return a User (See Login Identities), even if they match. For now, let’s just look at how the Identity Priority can affect which profile is returned by a request.

Example

User Profiles

Profile 1	Profile 2
Email: h.jekyll.md@example.com IDFV: 1234 Other: AAAA	Email: h.jekyll.md@example.com GAID: 2345 Other: BBBB

Scenarios

Identity Priority	Request	Results
1. Email Address 2. Other 3. IDFV 4. GAID	Email: h.jekyll.md@example.com Other:AAAA IDFV: 2345	First priority lookup (email) returns Profiles 1 and 2. Second priority (other) used as a tiebreaker. Profile 1 is returned.
1. Email Address 2. IDFV 3. GAID 4. Email Address	Email: h.jekyll.md@example.com GAID: 2345	First priority lookup (email) returns both Profiles 1 and 2. Second priority (IDFV) is not in the request, Third priority (GAID) used as a tiebreaker. Profile 2 is returned.

When Choosing your Identity Priority, ask the following questions about each of the identities you collect:

• Do your customers use the ID to login? Login IDs should be at the top of your hierarchy.
• Are they mutable? Some IDs may be changed by a user over time. Email is a good example. Generally, immutable IDs should rank higher than mutable IDs. Especially if they are used for Login.
• Does it permanently identify a user? Some IDs are anonymous - cookies, device advertising IDs or other temporary IDs used for experimentation. Generally speaking, these should rank lower than IDs that permanently identify a user.
• Is the ID shared across multiple apps or business areas in your organization?
• How likely are collisions for this ID?

Identity Strategy

An Identity Strategy is a set of rules that determine how mParticle should match Identity requests to User Profiles, when to update an existing profile and when to create a new one. Types of rules include:

Unique IDs

An Identity strategy can require some user identifiers to be unique. This means that only one mParticle Identity Record can have an ID. If an Identify or Modify request to the Identity API would result in two Identity Records sharing a Unique ID, mParticle will remove it from one Identity Record to enforce uniqueness. Note that this doesn’t mean all references to the identity are removed from the User Profile. The history of that User Profile remains intact. But removing the identifier from the Identity Record means it can no longer be used to lookup that profile. User Profiles with no remaining identifiers on their Identity Record are effectively ’orphaned’. They are not deleted but can never be returned by an Identity Request.

Example

User Profiles

A user signs up for your app with the email ed.hyde@example.com. The same person also interacts with your helpdesk, using the email address h.jekyll.md@example.com. Two user profiles are created, one for each email. Each has a unique mParticle ID:

Identity Record 1	Identity Record 2
MPID: 1234 Customer ID: h.jekyll.85 Email: ed.hyde@example.com IDFV: 1234	MPID: 5678 Email: h.jekyll.md@example.com

Scenarios

Unique IDs	Request	Results
Email	Type: Modify MPID: 1234 Customer ID: h.jekyll.85 Email h.jekyll.md@example.com IDFV: 1234	The modify request updates the email of Identity Record 1 to h.jekyll.md@example.com.Since emails must be unique, mParticle searches for other Identity Records with that email. The address is deleted from Identity Record 2, leaving it effectively ’orphaned’.
None	Type: Modify MPID: 1234 Customer ID: h.jekyll.85 Email h.jekyll.md@example.com IDFV: 1234	The modify request updates the email of Identity Record 1 to h.jekyll.md@example.com. Since email uniqueness is not enforced, both Identity Record 1 and Identity Record 2 now have the same email.

Login IDs

An Identity strategy can contain Login IDs. A Login ID is an identifier for a user that has created an account with your app. Login IDs perform two important functions. They protect the integrity of known user profiles, and they can drive Identity Rules that determine when a new Identity Record should be created.

Protect Known Identity Records

A Login ID identifies a single known user. In order to maintain the integrity of known Identity Records, a Record with at least one Login ID can ONLY be returned if the identify request includes a matching Login ID.

Example

Identity Records

Identity Record 1	Identity Record 2	Identity Record 3
Email: h.jekyll.md@example.com IDFV: 1234	Customer ID: h.jekyll.85 Email: ed.hyde@example.com IDFV: 2345	IDFV: 2345

Scenarios

Login IDs	Request	Results
Email	Email: h.jekyll.md@example.com IDFV: 1234	The request matches the Login ID of Identity Record 1. Identity Record 1 is returned.
Email	IDFV: 1234	The IDFV matches Profile 1, but since Profile 1 includes a Login ID, it cannot be returned to a request that doesn’t include the Login ID A new Identity Record is created.
Email Customer ID	Email: ed.hyde@example.com	Profile 2 has 2 login IDs, but we only need to match at least one to return the profile. Identity Record 2 is returned.

Handle New Known Users

One way Identity Strategies handle new known users is by applying rules about what to do when a new Login ID is received for the first time. A new Login ID always creates a new User Profile and Identity Record. Depending on the rule, both the new Known profile and the original anonymous profile can be kept separate, or they can be ’aliased’. Aliasing means:

• Most event data is copied over to the new User Profile
• The Audience builder looks at both profiles as one when making building audiences.
• The original anonymous Identity Record is now never returned in response to an Identity Request, the new aliased Record is returned instead.
• User Attributes are not copied over, but helper SDK methods are provided to copy attributes in persistence or local storage over to the new user.

Example

User Profiles

Identity Record 1
MPID: 2345 IDFV: 1234

Scenarios

Login ID Rule	Request	Results
Login ID: Email Rule: Create new unaliased profile on receipt of new Login ID	Type: Login Email h.jekyll.md@example.com IDFV: 1234	Since the request includes a Login ID that does not match any current profiles, a new profile is created , even though the Device ID in the request does match an existing profile.
Login ID: Email Rule: Create New Profile, Aliased to previous anonymous profile	Type: Login Email h.jekyll.md@example.com IDFV: 1234	The request includes a login ID that does not match any current profile, but an Anonymous profile for the device does exist. A new profile is created , with an Alias value of 2345 (the MPID of ID Record 1).