The MAUI SDK surfaces a series of APIs allowing you to manage user-identity state. These client-side APIs work in tandem with the mParticle Identity HTTP API and your configured Identity “strategy.” These APIs are designed generically but identity management requirements vary by app - so it’s crucial that you use the APIs correctly per your requirements.
\n\n| IdentityType | \nDescription | \n
|---|---|
customerid | \nIf you have an internal ID for your customer | \n
email | \nThe user’s email address | \n
facebook | \nThe user’s Facebook ID | \n
facebookcustomaudienceid | \nThe user’s Facebook App User ID that can be retrieved through the Facebook SDK | \n
google | \nThe user’s Google ID | \n
twitter | \nThe user’s Twitter ID | \n
microsoft | \nThe user’s Microsoft ID | \n
yahoo | \nThe user’s Yahoo ID | \n
other | \nAny other identifier that can contribute to user identification | \n
The mParticle Identity APIs surface four key operations (identify, login, logout, and modify). In the context of the MAUI SDK, the original ‘Identify’ request should be handled in your initialize code. See Getting Started
The login, logout and modify requests each accept an optional request object and a callback. Populating the request object correctly is crucial to managing the state of your users.
The IdentityRequest object is a holder for a set of identities that you would like to associate with the user. Populating the request object correctly is crucial to managing the state of your users. When you invoke any of the key Identity APIs with a request object, the identities it holds will be associated with the resulting user.
var request = new IdentityApiRequest() \n\t{\n\t\tUserIdentities = new Dictionary<UserIdentity, string>()\n\t\t{\n\t\t\t{UserIdentity.Email, \"h.jekyll.md@example.com\"}\n\t\t}\n\t};The Identity API lets you transition the SDK and data from one user to a new or different user. The Xamarin SDK maintains values in persistence that are associated with the current user, such as user attributes. If while transitioning you’d like to copy this data from the old user to the new user, you can define an onUserAlias callback to be invoked on a successful transition from one user to the next.
var request = new IdentityApiRequest() \n\t{\n\t\tUserIdentities = new Dictionary<UserIdentity, string>()\n\t\t{\n\t\t\t{UserIdentity.Email, \"h.jekyll.md@example.com\"}\n\t\t},\n\t\tUserAliasHandler = (previousUser, newUser) =>\n\t\t{\n var persistentAttribute = \"persistent user attribute\";\n var previousAttributes = previousUser.GetUserAttributes();\n if (previousAttributes.ContainsKey(persistentAttribute))\n {\n newUser.SetUserAttribute(persistentAttribute, previousAttributes[persistentAttribute]);\n }\n\t\t}\n\t};The Identify API is treated specially in that it’s called automatically on SDK initialization by the mParticle SDK. The SDK requires this call to succeed in order to establish an identity to associate with all data.
\nLogin and Logout should be invoked at the time of the user performing the matching or applicable actions in your application. These methods accept an Identity Request object, as created above. You can also create callback functions to handle success and failure.
\nvar identityApi = MParticle.Instance.Identity;\nidentityApi.Login(request)\n .AddSuccessListener(success => Console.WriteLine(success.User.GetUserAttributes()))\n .AddFailureListener(failure => Console.WriteLine(\"HttpCode = \" + failure.HttpCode + \"\\nErrors = \" + failure.Errors));var identityApi = MParticle.Instance.Identity;\nidentityApi.Logout()\n .AddSuccessListener(success => Console.WriteLine(success.User.GetUserAttributes()))\n .AddFailureListener(failure => Console.WriteLine(\"HttpCode = \" + failure.HttpCode + \"\\nErrors = \" + failure.Errors));Modify also has the identical signature, but note a crucial difference: modify actions will never result in a new user. Modify can only add, remove, or change the identities associated with an existing user. The mParticle SDK will compare the current user’s user identities with those that you supply within the IdentityApiRequest, in order to generate a delta and invoke the underlying Identity HTTP API.
In this example, the SDK will change the email of the current user, or add the email to the user’s profile if the user has no existing email on this device:
\nvar identityApi = MParticle.Instance.Identity;\nvar request = new IdentityApiRequest(identityApi.CurrentUser);\nrequest.UserIdentities[UserIdentity.Email] = \"ed.hyde@example.com\";\nidentityApi.Modify(request);Once the SDK has successfully called Identify for the first time, you will be able to access the current user via MParticle.Instance.Identity.CurrentUser:
var currentUser = MParticle.Instance.Identity.CurrentUser;\n\ncurrentUser.SetUserAttribute(\"color_preference\", \"green\");\ncurrentUser.SetUserTag(\"green\");Always refer to your organization’s data plan when instrumenting user or event attributes. Each unique attribute key becomes a data point in the mParticle UI that can be filtered for each Output, used to drive the calculation of an Audience or become part of a Custom Mapping. This means that your choice of attribute keys can have a system-wide impact. For example, if you have a single attribute key per device that represents a unique User ID or a unique URL, and you have thousands of users, mParticle will see thousands of unique keys, even though you only create one per device.
\nCreating too many unique attribute keys can have several adverse effects:
\nYou should avoid the following as attribute keys:
\nA gaming app has ten levels and you want to track which level each user has achieved.
\nBad option: Create ten tags - reachedLevel1, reachedLevel2, reachedLevel3, etc.
\nBetter option: Create a single attribute - reachedLevel = 4.
Capturing this data as a single attribute improves the performance of both your app and the mParticle dashboard by reducing the number of unique data points you need to manage. It’s also a much more useful data point. For example, you can easily create a single audience builder condition to target users within a range of levels reached.
\nAn mParticle Workspace can combine data from multiple platforms, for example it can show data from the same app running in iOS and Android. For this reason, you may wish to choose attribute names that you can keep consistent across all platforms for easier management. For example, if you call an attribute levelReached in iOS, LevelReached on Android, and level_reached on web, mParticle will treat these as three separate attributes.