MixpanelCppCX is a client for the Mixpanel analytics service. It has been built to handle the common situations of uploading events to the service. It supports batching, persisting-to-storage-before-uploading, and super properties.
It also supports the enagement/userprofile API. The official documentation will provide the right detail on how to use this part API.
It's intended to be consumed by any UWP app — but the original motivation was to support JavaScript applications.
MixpanelCppCX is published as a NuGET package
(Codevoid.Utilities.Mixpanel)
to the NuGET.org feed — just add it to your UWP Project in Visual Studio, and
it'll be available for use in your code.
- Items awaiting to upload are stored in a folder in your applications private
data folder with in local settings. (
%LOCALAPPDATA%\Packages\<PackageIdentity>\LocalState\MixpanelUploadQueue) - Items awaiting upload are written to disk after 500ms of idle time, or when there are 10 or more items in the queue — whichever comes first.
- Items are uploaded in batches of 50, unless one item in the batch fails, then they're uploaded 1 at a time.
- The queue is paused automatically when being suspended, and resumed when... resumed.
- This library does automatic session tracking — it starts tracking the session duration on start, and will automatically end/resume the session based on suspend/resume events.
- Create an instance of
Codevoid.Utilities.Mixpanel, and hold on to it.
var mixpanelClient = new Codevoid.Utilities.Mixpanel(<Mixpanel API Token>)
- Call, and wait for,
.InitializeAsync() - Call
.Start()on that instance to start processing the queue. - Call
.Track("MyEvent", null)to log a single event
If you need to send properties with your event you can use Windows.Foundation.Collections.PropertySet,
and insert your properties as needed, passing it as the second parameter to
Track:
var properties = new Windows.Foundation.Colllections.PropertySet();
properties.add("MyProperty", "MyValue");
properties.add("MyOtherProperty", 9);
mixpanelClient.Track("MyOtherEvent", properties);
If you want to be able to track your customers across multiple settings, and correlate the events that a device/customer generates, you need to set an identity for that user.
You can do that in two ways:
- Call
GenerateAndSetUserIdentityand create a GUID identifier - Use your own method for generating a unique identifier, and call
SetUserIdentityExplicitly.
From that point, any events will have that identifier logged.
If you want to check if you have identified this user, you can call HasUserIdentity.
Assuming you have an instance of MixpanelClient, you can set super properties
with three data types -- String, Double, and Boolean:
mixpanelClient.SetSuperPropertyAsString("PropertyName", "PropertyValue");
mixpanelClient.SetSuperPropertyAsDouble("DoublePropertyName", 3.14);
mixpanelClient.SetSuperPropertyAsBoolean("BooleanPropertyName", false);
Once set, the super properties will attached to every event when logged, automatically. This is useful for tracking against a single user, for example.
Assuming you have an instance of MixpanelClient, you can set session properties
with three data types -- String, Double, and Boolean:
mixpanelClient.SetSessionPropertyAsString("PropertyName", "PropertyValue");
mixpanelClient.SetSessionPropertyAsDouble("DoublePropertyName", 3.14);
mixpanelClient.SetSessionPropertyAsBoolean("BooleanPropertyName", false);
Once set, the session properties will attached to the session event when the session ends. This is useful to tracking how often something happened in a session
Once you've set the identity of the user, you are able to update the infromation that Mixpanel has about an identity -- this enables you to perform deeper analysis of your customer behaviour.
To update & change a profile, you can use the UpdateProfile API, and passing
properties to update those values.
mixpanelClient.UpdateUserProfile(UserProfileOperation.Set, propertySet);
Creates an instance of the class, and uses the supplied token to make the requests to Mixpanel.
var mixpanelClient = new Codevoid.Utilities.MixpanelClient("YOUR TOKEN HERE");
token — The token passed to the service with your events (required)
By default, all events have a time attached to them to indicate the order of the events, even if they're uploaded to the service out of order.
This property allows these to be disabled if you have your own way in which you set the time.
If you wish to override the time for a single event, include a property named "time" in the payload.
mixpanelClient.AutomaticallyAttachTimeToEvents = false;
By default, session duration is tracked & sent to the service. The session is started when Start() is called, and ends either when the app is suspended or when RestartSession()/Shutdown() is called.
Set this to false to have the session tracking turned off.
mixpanelClient.AutomaticallyTrackSessions = false;
When enabled, and even is tracked, it is immediately dropped, and never uploaded to the service. Intended to ube used in situations where the consumer offers a choice to their users about turning off all telemetry logging. With this option set, you can still call track, but nothing happens - it's immediately dropped.
Note, if you have events queued at this point they'll continue to be processed.
mixpanelClient.DropEventsForPrivacy = true;
Initializes the instance to be ready to process events, but does not start processing them. This gets the queue folder locally, and loads any unsent items from a previous session.
mixpanelClient.InitializeAsync().done(...);
Checks if a user identity has been set, and if so, returns 'true'.
mixpanelClient.HasUserIdentity();
Generates a random identifier for a user, and sets it for all future events. Any existing identity that may or may not be stored will be overwritten.
if(!mixpanelClient.HasUserIdentity()) {
mixpanelClient.GenerateAndSetUserIdentity();
}
Sets an explicit identifier for a user to be attached to all future events. Any existing identity will be overwritten.
mixpanelClient.SetUserIdentityExplicitly("User1");
identity - The user Identity be be set for future events.
Adds the event with the supplied name & properties (in addition to any super properties) to the upload queue. It is not sent immediately, and there are no promises/events to know when it's made it to the service.
mixpanelClient.Track("LoggedIn", null);
name — The name of the event that you are wishing to track
properties — The properties & values that are associated with this event.
Updates a users profile with the properties provided, applying the operation supplied. These follow the behaviour documented in Mixpanel's documentation.
operation — The type operation to perform with the provided properties.
properties — The properties & values to apply with the the provided operation
This enumeration maps to the specific operations that mixpanel allows for user profile operations.
Set — Sets the properties to the values provided, overwriting any that might
already exist. If they don't exist, they're created.
Set_Once — If a property already exists, then the value will not be updated.
If it doesn't, it will be created.
Add — Adds the numerical values of a property to an existing value, and saves
the result in that property. If the proeprty doesn't exist then it the values
provided are added to 0.
Append — Assumes that the values are sets, and appends the set to any existing
values that might be on the service.
Union — Assumes the values are sets, and merges the set to any existing values
that might be on the service. If an value in the set is already there, it is not
duplicated.
Remove — Assumes values are sets, and removes any items in the set from the
values that might be on the service.
Unset — Removes the entire property from the users profile, like it had never
been there.
Clears any user identity that might be set, so that future events are no longer associated with a user.
This should be called after a ClearSuperProperties to truely return to a default
state.
Asks Mixpanel to delete the information related to the current user identity. It also clears any local user identity that is stored.
name — Name of the event that is being logged (required)
properties — Any additional properties you would like to log with this event (optional)
Starts a timing the duration of an event. After this, if an event is tracked
through Track with the same name, a duration property will be attached to
the event when tracked.
mixpanelClient.StartTimedEvent("LoggedIn");
Explicitly starts a restarts session. If there is one already in progress, the in progress session will be ended, otherwise starts one. Intended to be used in situations where your session doesn't always match between suspend & resume. E.g. you want to start a session when someone logs in.
mixpanelClient.RestartSessionTracking();
name — Name of the event that the duration is to be tracked (required)
Sets a session property on the class, that is persisted for the duration of the
session. You can store string's, integer's, double's, and boolean's.
When consuming this, you need to use the named versions of this method:
SetSessionPropertyAsString for strings, SetSessionPropertyAsIntegter for
integers, SetSessionPropertyAsDouble for doubles, and
SetSessionPropertyAsBoolean for, obviously, Booleans.
mixpanelClient.SetSessionProperty("ASessionProperty", "SessionValue");
name — Name of the property that is to be set (required)
value — Value to be set for the supplied name (required)
Retrieves a value from the session property storage, and returns it to the caller.
Since they're all different only in their return type, and accept the same parameters, they're named differently based on their datatype.
var currentValue = mixpanelClient.GetSessionProperty("ASessionProperty");
name — Named session property to retrieve.
Checks if a session property has been set & has a value.
if(mixpanelClient.HasSessionProperty("ASessionProperty")) {
console.log("ASessionProperty has been set");
}
name — Property to check for being set.
Removes a session property from the set of session properties. If the property isn't set, then the method returns silently.
mixpanelClient.RemoveSessionProperty("ASessionProperty");
name — Property to remove.
Clears all currently set session properties.
mixpanelClient.ClearSessionProperties();
Sets a super property on the class, that is persisted across instances. You can
store string's, int's,double's, and boolean's. When consuming this, you
need to use the named versions of this method:
SetSuperPropertyAsString for strings, SetSuperPropertyAsInteger for integers,
SetSuperPropertyAsDouble for doubles, and SetSuperPropertyAsBoolean for,
obviously, Booleans.
mixpanelClient.SetSuperProperty("ASuperProperty", "SuperValue");
name — Name of the property that is to be set (required)
value — Value to be set for the supplied name (required)
Retrieves a value from the super property storage, and returns it to the caller.
Since they're all different only in their return type, and accept the same parameters, they're named differently based on their datatype.
var currentValue = mixpanelClient.GetSuperProperty("ASuperProperty");
name — Named super property to retrieve.
Checks if a super property has been set & has a value.
if(mixpanelClient.HasSuperProperty("ASuperProperty")) {
console.log("ASuperProperty has been set");
}
name — Property to check for being set.
Removes a super property from the set of super properties. If the property isn't set, then the method returns silently.
mixpanelClient.RemoveSuperProperty("ASuperProperty");
name — Property to remove.
Clears all currently set super properties, excluding the user identity. To clear
that, call ClearUserIdentity.
mixpanelClient.ClearSuperProperties();
Starts processing any events that are queued.
mixpanelClient.Start();
Drains the queue to storage, and stops processing any events pending upload to the service.
Once you're ready to process events again, call Start().
mixpanelClient.PauseAsync().done(...);
Removes any events that have been queued to storage, but have not been uploaded to the service yet.
mixpanelClient.ClearStorageAsync().done(...);