项目作者: grork

项目描述 :
Mixpanel Client for the UWP platform written in C++
高级语言: C++
项目地址: git://github.com/grork/MixpanelClient.git
创建时间: 2018-02-25T00:39:55Z
项目社区:https://github.com/grork/MixpanelClient

开源协议:MIT License

下载


MixpanelCppCX

Introduction

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.

How to get it

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.

Things to note

  • 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.

Usage

Sending a simple event

  1. Create an instance of Codevoid.Utilities.Mixpanel, and hold on to it.
    1. var mixpanelClient = new Codevoid.Utilities.Mixpanel(<Mixpanel API Token>)
  2. Call, and wait for, .InitializeAsync()
  3. Call .Start() on that instance to start processing the queue.
  4. 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:

  1. var properties = new Windows.Foundation.Colllections.PropertySet();
  2. properties.add("MyProperty", "MyValue");
  3. properties.add("MyOtherProperty", 9);
  4. mixpanelClient.Track("MyOtherEvent", properties);

Setting a User Identity

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:

  1. Call GenerateAndSetUserIdentity and create a GUID identifier
  2. 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.

Adding a super property

Assuming you have an instance of MixpanelClient, you can set super properties
with three data types — String, Double, and Boolean:

  1. mixpanelClient.SetSuperPropertyAsString("PropertyName", "PropertyValue");
  2. mixpanelClient.SetSuperPropertyAsDouble("DoublePropertyName", 3.14);
  3. 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.

Adding a session property

Assuming you have an instance of MixpanelClient, you can set session properties
with three data types — String, Double, and Boolean:

  1. mixpanelClient.SetSessionPropertyAsString("PropertyName", "PropertyValue");
  2. mixpanelClient.SetSessionPropertyAsDouble("DoublePropertyName", 3.14);
  3. 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

Updating & Storing User Profiles

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.

  1. mixpanelClient.UpdateUserProfile(UserProfileOperation.Set, propertySet);

API

MixpanelClient(String token) (Constructor)

Creates an instance of the class, and uses the supplied token to make the
requests to Mixpanel.

  1. var mixpanelClient = new Codevoid.Utilities.MixpanelClient("YOUR TOKEN HERE");

Parameters

token — The token passed to the service with your events (required)

Properties

bool AutomaticallyAttachTimeToEvents

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.

  1. mixpanelClient.AutomaticallyAttachTimeToEvents = false;

bool AutomaticallyTrackSessions

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.

  1. mixpanelClient.AutomaticallyTrackSessions = false;

bool DropEventsForPrivacy

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.

  1. mixpanelClient.DropEventsForPrivacy = true;

Methods

IAsyncAction InitializeAsync()

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.

  1. mixpanelClient.InitializeAsync().done(...);

bool HasUserIdentity()

Checks if a user identity has been set, and if so, returns ‘true’.

  1. mixpanelClient.HasUserIdentity();

void GenerateAndSetUserIdentity()

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.

  1. if(!mixpanelClient.HasUserIdentity()) {
  2. mixpanelClient.GenerateAndSetUserIdentity();
  3. }

void SetUserIdentityExplicitl(String identity)

Sets an explicit identifier for a user to be attached to all future events. Any
existing identity will be overwritten.

  1. mixpanelClient.SetUserIdentityExplicitly("User1");

Parameters

identity - The user Identity be be set for future events.

void Track(String name, IPropertySet properties)

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.

  1. mixpanelClient.Track("LoggedIn", null);

Parameters

name — The name of the event that you are wishing to track

properties — The properties & values that are associated with this event.

void UpdateUserProfile(UserProfileOperation operation, IPropertySet properties)

Updates a users profile with the properties provided, applying the operation
supplied. These follow the behaviour documented in Mixpanel’s documentation.

Parameters

operation — The type operation to perform with the provided properties.

properties — The properties & values to apply with the the provided operation

UserProfileOperation

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.

void ClearUserIdentity()

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.

void DeleteUserProfile()

Asks Mixpanel to delete the information related to the current user identity.
It also clears any local user identity that is stored.

Parameters

name — Name of the event that is being logged (required)

properties — Any additional properties you would like to log with this event (optional)

void StartTimedEvent(string name)

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.

  1. mixpanelClient.StartTimedEvent("LoggedIn");

void RestartSessionTracking()

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.

  1. mixpanelClient.RestartSessionTracking();

Parameters

name — Name of the event that the duration is to be tracked (required)

void SetSessionPropertyAs(String name, [String/Integer/Double/Boolean] value)

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.

  1. mixpanelClient.SetSessionProperty("ASessionProperty", "SessionValue");

Parameters

name — Name of the property that is to be set (required)
value — Value to be set for the supplied name (required)

string/double/bool GetSessionPropertyAsString/Integer/Double/Boolean(string name)

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.

  1. var currentValue = mixpanelClient.GetSessionProperty("ASessionProperty");

Parameters

name — Named session property to retrieve.

bool HasSessionProperty(string name)

Checks if a session property has been set & has a value.

  1. if(mixpanelClient.HasSessionProperty("ASessionProperty")) {
  2. console.log("ASessionProperty has been set");
  3. }

name — Property to check for being set.

void RemoveSessionProperty(string name)

Removes a session property from the set of session properties. If the property isn’t
set, then the method returns silently.

  1. mixpanelClient.RemoveSessionProperty("ASessionProperty");

Parameters

name — Property to remove.

void ClearSessionProperties()

Clears all currently set session properties.

  1. mixpanelClient.ClearSessionProperties();

void SetSuperPropertyAs(String name, [String/Integer/Double/Boolean] value)

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.

  1. mixpanelClient.SetSuperProperty("ASuperProperty", "SuperValue");

Parameters

name — Name of the property that is to be set (required)

value — Value to be set for the supplied name (required)

string/double/bool GetSuperPropertyAsString/Integer/Double/Boolean(string name)

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.

  1. var currentValue = mixpanelClient.GetSuperProperty("ASuperProperty");

Parameters

name — Named super property to retrieve.

bool HasSuperProperty(string name)

Checks if a super property has been set & has a value.

  1. if(mixpanelClient.HasSuperProperty("ASuperProperty")) {
  2. console.log("ASuperProperty has been set");
  3. }

name — Property to check for being set.

void RemoveSuperProperty(string name)

Removes a super property from the set of super properties. If the property isn’t
set, then the method returns silently.

  1. mixpanelClient.RemoveSuperProperty("ASuperProperty");

Parameters

name — Property to remove.

void ClearSuperProperties()

Clears all currently set super properties, excluding the user identity. To clear
that, call ClearUserIdentity.

  1. mixpanelClient.ClearSuperProperties();

void Start()

Starts processing any events that are queued.

  1. mixpanelClient.Start();

IAsyncAction PauseAsync()

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().

  1. mixpanelClient.PauseAsync().done(...);

IAsyncAction ClearStorageAsync()

Removes any events that have been queued to storage, but have not been uploaded
to the service yet.

  1. mixpanelClient.ClearStorageAsync().done(...);