SDK Reference updated for MarkedUp Analytics SDK for .NET 1.0.

Assembly Info

WinRT

Namespace: MarkedUp

Assembly Name: MarkedUp.winmd

WinJS

JavaScript File: MarkedUp.js

Global Object: MK

Windows Phone

Namespace: MarkedUp

Assembly Name: MarkedUp.dll


Member Overview


Required Methods

Initialize(apiKey) Method - required in order to run MarkedUp!

Initialize(apiKeys[]) Method - enables multiple reporting streams for MarkedUp clients

Logging Methods

Error Method
Fatal Method
Trace Method
Info Method
Debug Method

LogLastChanceException Method

Custom Session Event Methods

SessionEvent Method

Navigation Methods

RegisterNavigationFrame Method

PageEnter Method
PageExit Method

Commerce Methods

InAppPurchase Object

InAppPurchaseCompleted Method

TrialConversion Object

TrialConversionCompleted Method

Opt-Out / Opt-In Methods

OptOut Method

Miscellaneous Methods

OrientationChanged Method


Remarks

The AnalyticClient is the main object within the MarkedUp SDK providing static and instance API for interacting with the MarkedUp analytic service.

To use the static API simply call the static Initialize method passing in an API key obtained from the analytic dashboard. To use the instance API call the constructor of the AnalyticClient passing in an API key obtained from the analytic dashboard.



Static Methods

The static methods off of the AnalyticClient are convenience methods that wrap a singleton instance of the AnalyticClient.

Initialize(apiKey) Method

The static Initialize method is used to initialize the static instance of the AnalyticClient.

Signature

WinRT and Windows Phone 8

static void Initialize(string apiKey)

Parameters

  • string apiKey The API key used to initialize the AnalyticClient

WinJS

MK.initialize(apiKey)

Parameters

  • string apiKey The API key used to initialize the static instance of the AnalyticClient

Remarks
The static initialize method is used initialize the static API of the AnalyticClient object. It must be called before any other static members are called off the AnalyticClient. Calls made to the static API before the Initialize method is called are NoOps, meaning they will have no effect.



Initialize(apiKeys[]) Method

The static Initialize method is used to initialize the AnalyticClient instance so MarkedUp can begin reporting. This overload of the Initialize method accepts an array of one or more API keys and will transmit all events that occur on each SDK call to all of the MarkedUp apps that correspond with each API key. Useful if you're tracking multiple binaries in the Windows Store or elsewhere.

Signature

WinRT and Windows Phone 8

static void Initialize(string apiKeys[])

Parameters

  • string apiKey The API key used to initialize the static instance of the AnalyticClient

WinJS

MK.initialize(apiKeys[])

Parameters

  • string[] apiKeys An array of MarkedUp API keys - one for each reporting stream.

Remarks
You can only call initialize once, so if you intend to track multiple reporting streams make sure you use this method.



Logging Methods

Logging methods are used to capture diagnostic logging messages. These methods are useful when you want to capture events of interest that happen during the execution of your app like exceptions.


Trace Method

The static Trace method is used to create a trace level diagnostic message.

Signature

WinRT and Windows Phone 8

static void Trace(string message, Exception exception, IDictionary<string,string> state)

Parameters

  • string message - The message to send with the log message
  • (optional) Exception exception - An exception to upload along with the log message
  • (optional) IDictionary<string,string> state - The state dictionary is used to upload application-specific data along with log message

WinJS

MK.trace(string message, [object exception], [Windows.Foundation.Collections.PropertySet state]) 

Parameters

  • string message - The message to send with the log message
  • (optional) Exception exception - An exception to upload along with the log message
  • (optional) Windows.Foundation.Collections.PropertySet state - The state dictionary is used to upload application data along with log message. Must be a Windows.Foundation.Collections.PropertySet object in WinJS.

Remarks
Trace level log message are useful for capturing verbose events.



Debug Method

The static Debug method is used to create a debug level diagnostic message.

Signature

WinRT and Windows Phone 8

static void Debug(string message, Exception exception, IDictionary<string,string> state)

Parameters

  • string message - The message to send with the log message
  • (optional) Exception exception - An exception to upload along with the log message
  • (optional) IDictionary<string,string> state - The state dictionary is used to upload application-specific data along with log message

WinJS

MK.debug(string message, [object exception], [Windows.Foundation.Collections.PropertySet state]) 

Parameters

  • string message - The message to send with the log message
  • (optional) Exception exception - An exception to upload along with the log message
  • (optional) Windows.Foundation.Collections.PropertySet state - The state dictionary is used to upload application data along with log message. Must be a Windows.Foundation.Collections.PropertySet object in WinJS.

Remarks
Debug level log message are meant for capturing information for debugging purposes only.



Info Method

The static Info method is used to create a info level diagnostic message.

Signature

WinRT and Windows Phone 8

static void Info(string message, Exception exception, IDictionary<string,string> state)

Parameters

  • string message - The message to send with the log message
  • (optional) Exception exception - An exception to upload along with the log message
  • (optional) IDictionary<string,string> state - The state dictionary is used to upload application-specific data along with log message

WinJS

MK.info(string message, [object exception], [Windows.Foundation.Collections.PropertySet state]) 

Parameters

  • string message - The message to send with the log message
  • (optional) Exception exception - An exception to upload along with the log message
  • (optional) Windows.Foundation.Collections.PropertySet state - The state dictionary is used to upload application data along with log message. Must be a Windows.Foundation.Collections.PropertySet object in WinJS.

Remarks
Info level log message are useful for capturing events of interest.



Error Method

The static Error method is used to create a error level diagnostic message.

Signature

WinRT and Windows Phone 8

static void Error(string message, Exception exception, IDictionary<string,string> state)

Parameters

  • string message - The message to send with the log message
  • (optional) Exception exception - An exception to upload along with the log message
  • (optional) IDictionary<string,string> state - The state dictionary is used to upload application-specific data along with log message

WinJS

MK.error(string message, [object exception], [Windows.Foundation.Collections.PropertySet state])

Parameters

  • string message - The message to send with the log message
  • (optional) Exception exception - An exception to upload along with the log message
  • (optional) Windows.Foundation.Collections.PropertySet state - The state dictionary is used to upload application data along with log message. Must be a Windows.Foundation.Collections.PropertySet object in WinJS.

Remarks
Error level log message are useful for capturing events involving non fatal exceptions.



Fatal Method

The static Fatal method is used to create a fatal level diagnostic message.

Signature

WinRT and Windows Phone 8

static void Fatal(string message, Exception exception, IDictionary<string,string> state)

Parameters

  • string message - The message to send with the log message
  • (optional) Exception exception - An exception to upload along with the log message
  • (optional) IDictionary<string,string> state - The state dictionary is used to upload application-specific data along with log message

WinJS

MK.fatal(string message, [object exception], [Windows.Foundation.Collections.PropertySet state])

Parameters

  • string message - The message to send with the log message
  • (optional) Exception exception - An exception to upload along with the log message
  • (optional) Windows.Foundation.Collections.PropertySet state - The state dictionary is used to upload application data along with log message. Must be a Windows.Foundation.Collections.PropertySet object in WinJS.

Remarks
Fatal level log message are useful for capturing events involving last chancne unhandled exceptions.



LogLastChanceException Method

The static LogLastChanceException method is used in last chance exception handlers to log unhandled exceptions.

Signature

WinRT and Windows Phone 8

static void LogLastChanceException(UnhandledExceptionEventArgs ex)

Parameters

  • UnhandledExceptionEventArgs ex - The UnhandledExceptionEventArgs from the Application.UnhandledException handler that contains the unhandled exception details.

Remarks (WinRT) As of MarkedUp Analytics SDK for .NET 1.0, this method is now called automatically by MarkedUp internally and does not need to be called explicitly by a developer (but you still can if you want to.)

WinJS

MK.logLastChanceException(object errorInfo)

Parameters

  • object errorInfo - The errorInfo object from the WinJS.Application.onerror handler that contains the the unhandled error details.

Remarks
The LogLastChanceException is designed to reliable log exceptions that are propergated to last chance event handlers.This method should only be called from the last chance exception handler of the app as it is designed to block the calling thread's execution until exception details have been persisted to disk.



Navigation Methods

Navigation methods are used to capture the paths that users take throughout your application - it allows you to record not only which pages they viewed, but also which pieces of UI they used to execute a custom event, in-app purchase, diagnostic log, or any other sort of event.



RegisterNavigationFrame Method

The static RegisterNavigationFrame method is used to automatically track navigation events within the current analytic session of the AnalyticClient.

Signature

WinRT

static void RegisterNavigationFrame(Frame navigationFrame)  

Parameters

  • Frame navigationFrame - The frame used for navigation events

WinJS

MK.registerNavigationFrame()  

Parameters

No parameters required for this method in WinJS.

Windows Phone 8

static void RegisterNavigationFrame(PhoneApplicationFrame navigationFrame)  

Parameters

  • PhoneApplicationFrame navigationFrame - The frame used for navigation events inside Windows Phone 8.

Remarks
Call this method when you want MarkedUp to automatically log navigation events through your app's navigation frame. This method is usually called inside the app.onactivated method in default.js in WinJS or Application.OnLaunched in App.xaml.xs in C#/XAML.



PageEnter Method

The static PageEnter method is used to raise a page enter event within the current analytic session of the AnalyticClient.

Signature

WinRT and Windows Phone 8

static void PageEnter(string page)  

Parameters

  • string page - The name of the page being entered

WinJS

MK.enterPage(string page)  

Parameters

  • string page - The name of the page being entered

Remarks
Call this method when you want to capture when a user enters a page.



PageExit Method

The static PageExit method is used to raise a page exit event within the current analytic session of the AnalyticClient.

Signature

WinRT and Windows Phone 8

static void PageExit(string page)

Parameters

  • string page - The name of the page being exited

WinJS

MK.exitPage(string page)  

Parameters

  • string page - The name of the page being exited

Remarks
Call this method when you want to capture when a user exits a page.



Session Event Methods

These methods allow developers to create special events unique to their apps, and also include the ability to create parameters and parameter groups for those events as well.

SessionEvent Method

The static SessionEvent method is used to raise custom events within the current analytic session of the AnalyticClient.

Signature

WinRT and Windows Phone 8

static void SessionEvent(string eventName, [IDictionary<string, string> parameters])

Parameters

  • string eventName - The name of the custom event
  • (optional) IDictionary<string,string> parameters - A dictionary of custom parameter names and values; allows you to use session events to group other sub-events into categories.

WinJS

MK.sessionEvent(string eventName, [Windows.Foundation.Collections.PropertySet parameters]))  

Parameters

  • string eventName - The name of the custom event
  • (optional) Windows.Foundation.Collections.PropertySet parameters - - A dictionary of custom parameter names and values; allows you to use session events to group other sub-events into categories. Must be a Windows.Foundation.Collections.PropertySet object in WinJS.

Remarks
Call this method when you want to capture custom events. This is useful when you want to see how often something occurs in the app.



Commerce Methods

Commerce methods are intended to help developers who are using a trial model or sell in-app purchases track their revenues globally and understand their conversion funnel along the way.

InAppPurchase Object

Ever since the release of MarkedUp v1.06, all in-app commerce methods now take an InAppPurchase object as their only argument. This object gives the developer full control over their in-app products and contains all of the information MarkedUp needs in order to process purchase totals.

Class Definition (C#)

/// <summary>
/// Class that represents an in-app purchase - designed to be used
/// with the InAppPurchaseCompleted event
/// </summary>
public sealed class InAppPurchase
{
    /// <summary>
    /// [REQUIRED] The unique identifier for this product.
    /// 
    /// For TrialConversion events, this defaults to the ID for this app if left blank.
    /// </summary>
    public string ProductId { get; set; }

    /// <summary>
    /// [REQUIRED] The human-readble name for this product.
    /// 
    /// For TrialConversion events, this defaults to the name for this app if left blank.
    /// </summary>
    public string ProductName { get; set; }

    /// <summary>
    /// The Currency that this transaction is using (i.e. "USD" for US Dollars, "EUR" for Euros, etc...)
    /// 
    /// If this field is left blank the value will be populated using the user's default region and currency settings.
    /// </summary>
    public string Currency { get; set; }

    /// <summary>
    /// The price of this in-app purchase in the <Currency/> specified.
    /// 
    /// Defaults to 0.00!
    /// </summary>
    public double Price { get; set; }

    /// <summary>
    /// The current market for this user (i.e. "US" for United States, "CA" for Canada, etc...)
    /// 
    /// If left blank, this value will be automatically populated with the user's current region settings
    /// </summary>
    public string CurrentMarket { get; set; }

    /// <summary>
    /// The name of the commerce engine being used. If you're using the Windows Store, leave this value blank.
    /// 
    /// Otherwise, if you're using PayPal, Amazon Payments, or any other custom commerce system please
    /// specify that value here.
    /// </summary>
    public string CommerceEngine { get; set; }
}

Example (C#)

//All of this data can be mapped from a ProductListing via the Windows.ApplicationModel.Store namespace 
var iap = new MarkedUp.InAppPurchase() 
{ 
    ProductId = "SampleIAP1", 
    ProductName = "Sample In-App Purchase", 
    CurrentMarket = RegionInfo.CurrentRegion.TwoLetterISORegionName, 
    CommerceEngine = "Windows Store", //or a third-party engine, like PayPal
    CurrentRegionency = RegionInfo.CurrentRegion.ISOCurrencySymbol, 
    Price = 2.59 
};

Example (WinJS)

var region = new Windows.Globalization.GeographicRegion();
var iap = new MarkedUp.InAppPurchase();
    iap.productId = "SampleIAP1";
    iap.productName = "Sample In-app Purchase";
    iap.currentMarket = region.code;
    iap.currency = region.currenciesInUse.getAt(0);
    iap.commerceEngine = "Windows Store"; //or a third-party engine, like PayPal
    iap.price = 1.79; 



InAppPurchaseComplete Method

The static InAppPurchaseComplete method is used to raise an in-app purchase completed event within the current analytic session. This is the method responsible for capturing all final in-app purchase revenue / transaction totals inside MarkedUp!

Signature

WinRT and Windows Phone 8

static void InAppPurchaseComplete(InAppPurchase iap)  

Parameters

  • InAppPurchase iap - An (InAppPurchase)[#in-app-purchase-object] instance.

WinJS

MK.inAppPurchaseComplete(InAppPurchase iap)  

Parameters

  • InAppPurchase iap - An (InAppPurchase)[#in-app-purchase-object] instance.

Remarks
Call this method when you want to capture when an in-app purchase is completed.



TrialConversion Object

Ever since the release of MarkedUp v1.06, all trial / free-to-paid conversion commerce methods now take an TrialConversion object as their only argument. This object gives the developer full control over their in-app products and contains all of the information MarkedUp needs in order to process purchase totals.

Class Definition (C#)

/// <summary>
/// Class that represents a conversion from a free (trial) to a fully paid app.
/// Intended to be used with the TrialConversionCompleted event
/// </summary>
public sealed class TrialConversion
{
    /// <summary>
    /// The unique identifier for this product.
    /// 
    /// For TrialConversion events, this defaults to the ID for this app if left blank.
    /// </summary>
    public string ProductId { get; set; }

    /// <summary>
    /// The human-readble name for this product.
    /// 
    /// For TrialConversion events, this defaults to the name for this app if left blank.
    /// </summary>
    public string ProductName { get; set; }

    /// <summary>
    /// The Currency that this transaction is using (i.e. "USD" for US Dollars, "EUR" for Euros, etc...)
    /// 
    /// If this field is left blank the value will be populated using the user's default region and currency settings.
    /// </summary>
    public string Currency { get; set; }

    /// <summary>
    /// The price of this in-app purchase in the <Currency/> specified.
    /// 
    /// Defaults to 0.00!
    /// </summary>
    public double Price { get; set; }

    /// <summary>
    /// The current market for this user (i.e. "US" for United States, "CA" for Canada, etc...)
    /// 
    /// If left blank, this value will be automatically populated with the user's current region settings
    /// </summary>
    public string CurrentMarket { get; set; }

    /// <summary>
    /// The name of the commerce engine being used. If you're using the Windows Store, leave this value blank.
    /// 
    /// Otherwise, if you're using PayPal, Amazon Payments, or any other custom commerce system please
    /// specify that value here.
    /// </summary>
    public string CommerceEngine { get; set; }
}

Example (C#)

//All of this data can be mapped from a ListingInformation via the Windows.ApplicationModel.Store namespace on WinRT
var tc = new TrialConversion()
{
    ProductId = "FreeToPaid1",
    ProductName = "Free Tier to Basic Paid Tier",
    CurrentMarket = RegionInfo.CurrentRegion.TwoLetterISORegionName,
    CommerceEngine = "Custom Engine",
    Currency = RegionInfo.CurrentRegion.ISOCurrencySymbol,
    Price = 5.99
};

Example (WinJS)

var region = new Windows.Globalization.GeographicRegion();
var tc = new MarkedUp.TrialConversion();
    tc.currency = region.currenciesInUse.getAt(0);
    tc.commerceEngine = "Custom Commerce";
    tc.price = 4.79;
    tc.currentMarket = region.code;



TrialConversionComplete Method

The static TrialConversionComplete method is used to raise a trial conversion offer completed event within the current analytic session. This is the method responsible for capturing all final trial conversion revenue / transaction totals inside MarkedUp!

Signature

WinRT and Windows Phone 8

static void TrialConversionComplete(TrialConversion tc)  
  • TrialConversion tc - An (TrialConversion)[#trial-conversion-object] instance.

WinJS

MK.trialConversionComplete(TrialConversion tc)  
  • TrialConversion tc - An (TrialConversion)[#trial-conversion-object] instance.

Remarks
Call this method when you want to capture when a trial conversion offer is completed.



OptOut Method

If you want to give your users control over whether or not you're able to collect information on them, the OptOut method can be used to allow users to opt-out or opt-in to MarkedUp Analytics.

This method will record an opt-out or opt-in event on your dashboard, and it will leave a local artifact on the end-user's device letting MarkedUp know that this user can't be tracked. You won't see any more data for a user who opts out.

N.B. MarkedUp tracks users by default.

Signature

WinRT and Windows Phone 8

static void OptOut(bool optOutPreference)

Parameters * bool optOutPreference - If set to true, a user will be opted-out of all tracking in the future. If set to false, a user may opt-back into tracking. Users are tracked by default.

WinJS

MK.optOut(bool optOutPreference)  

Parameters * bool optOutPreference - If set to true, a user will be opted-out of all tracking in the future. If set to false, a user may opt-back into tracking. Users are tracked by default.



OrientationChanged Method

The static OrientationChanged method is used to raise an orientation changed event within the current analytic session of the AnalyticClient.

Signature

WinRT and Windows Phone 8

static void OrientationChanged(string page, string orientation)

Parameters

  • string page - The name of the current page
  • DeviceOrientation orientation - The current orientation of the device

WinJS

MK.orientationChange(string page, DeviceOrientation orientation)  

Parameters

  • string page - The name of the page being exited
  • string query - The current orientation of the device

Remarks
Call this method when you want to capture the devices current orientation.




Last Updated: 11/22/2013 1:05:39 AM