JavaScript API Reference

Medio.EventApi methods:

Medio.MedioEventExtras methods:

Medio.LogPurchaseOptions methods:

Medio.LogEarnOptions methods:

Medio.EventApi


Medio.EventApi.initialize

boolean initialize(apiKey)

Initializes the SDK with your Medio Platform API key.

Parameters:

  • apiKey: The Medio Platform API key for your web application.

Returns:
true if the SDK initialized successfully, false otherwise.


Medio.EventApi.logPageRequest

boolean logPageRequest()

Logs an event indicating a browser request for a specific page. You can call this method when the browser loads a page to automatically include the following information as key-value pairs:

  • referrerUri: The URI of the referring page.
  • locationUri: The URI of the current page.
  • screenHeight: The height of the screen (in pixels).
  • screenWidth: The width of the screen (in pixels).
  • screenPixelDepth: The screen resolution (in bits per pixel).
  • screenColorDepth: The bit depth of the color palette.

You must call Medio.EventApi.initialize prior to calling this method.

Returns:
true if the page request was logged successfully and Medio.EventApi.initialize was successfully called prior to calling this method, false otherwise.


Medio.EventApi.logEvent

boolean logEvent(type, keyValuePairs)

Logs an event with optional key-value pairs as parameters. You must call Medio.EventApi.initialize prior to calling this method.

Parameters:

  • type: The type or name of the event to log. This string must be 64 characters or less in length and must only contain characters matching the following regular expression: ^[a-zA-Z][a-zA-Z0-9._-]*$.
  • keyValuePairs: A map of key-value pairs corresponding to the event being logged. The maximum number of key-value pairs is 255. This parameter can be null. The length of each key should be less than 64 characters. The keys should not start with “__” and should not have “=” anywhere in the name. Any null keys will be ignored, while null values will be converted to a string with a value of “null”.

Returns:
true if the event type is valid and Medio.EventApi.initialize was successfully called prior to calling this method, false otherwise.

Example:

//log the window's current scroll offsets whenever it is scrolled. 
window.onscroll = function f() {     
    Medio.EventApi.logEvent("scroll", {x: window.scrollX, y: window.scrollY});
}


Medio.EventApi.setProperties

void setProperties(jsProperties)

Sets optional SDK properties. Your web application may call this method at any time. Only the properties that you specify in each call are updated.

Parameters:

  • jsProperties: A JavaScript object with a field for each property to set. You may specify the following properties (default values in parentheses):
    • autoFlush (true): specifies whether automatic flushing should be enabled or disabled.
    • trackLocation (false): enables or disables location tracking.
    • partnerId (null): specifies a partner ID to log with each event. For example, if your application has version 1.0, but is branded for sponsors A, B, and C, then you may specify A, B, or C as a partner ID to differentiate between the different sponsor brands.
    • productName (null): specifies a name for your application.
    • productVersion (null): specifies a version for your application.
    • userId (null): specifies an application-defined ID for the user such as a numeric ID or username. We recommend that you hash your user IDs before setting them if they contain any personally identifiable information. If you don’t set a user ID then we’ll use an automatically-generated anonymous ID in combination with other factors to identify the user.

Example:

var customProperties = {};
customProperties.autoFlush = true;
customProperties.userId = “1234”;
Medio.EventApi.setProperties(customProperties);


Medio.EventApi.setCommonKeyValuePairs

void setCommonKeyValuePairs(keyValuePairs)

Optionally add key-value pairs to all events logged. This is a convenience method for automatically adding key-value pairs to each event logged instead of explicitly adding the same key-value pairs to each event.

Your application should set these common key-value pairs every time the page reloads. Additionally, your application should update or remove these key-value pairs if their values change or if they no longer apply. The SDK will only add common key-value pairs to new events logged after calling this method.

Please keep in mind the maximum number of key-value pairs is 255 per event and common key-value pairs will count against the 255 maximum. In case the maximum is exceeded on a particular event, then the common key-value pairs will be dropped first.

Parameters:

  • keyValuePairs: A map of key-value pairs to automatically add to each event logged. null keys are not allowed and will be ignored. null values will be converted to the “null” string. Numbers, Dates, and JavaScript Objects and Arrays will be converted to strings using the toString method.

Example:

var commonKeyValuePairs = {};
commonKeyValuePairs.userIsLoggedIn = false;
Medio.EventApi.setCommonKeyValuePairs(commonKeyValuePairs);


Medio.EventApi.removeCommonKeyValuePairs

void removeCommonKeyValuePairs(keys)

Removes common key-value pairs that were previously added with Medio.EventApi.setCommonKeyValuePairs.

Parameters:

  • keys: An array of keys of the key-value pairs to remove.

Example:

Medio.EventApi.removeCommonKeyValuePairs("myKey1", "myKey2");


Medio.EventApi.flushEvents

void flushEvents()

Manually flushes events to the server. You must initialize the SDK using Medio.EventApi.initialize before calling this method. You can call this method regardless of whether automatic flushing is enabled. This method assumes that the device has a data connection available. If no data connection is available, this method will do nothing.


Medio.EventApi.extras

Object extras()

Returns a reference to the Medio.MedioEventExtras singleton.

Returns:
A reference to the Medio.MedioEventExtras singleton.


Medio.EventApi.setFlightId

void setFlightId(flightId)

For applications conducting A/B tests, optionally set this property to add the user’s A/B test flight identifier to all logged events. If you have previously set this property and set it to a new value, the new value will be added to all events logged thereafter.

Parameters:

  • flightId: The flight ID to set.


Medio.EventApi.setGameLevel

void setGameLevel(gameLevel)

For gaming applications, optionally set this property to add the user’s game level to all logged events. If you have previously set this property and set it to a new value, the new value will be added to all events logged thereafter.

Parameters:

  • gameLevel: The game level to set.

Medio.MedioEventExtras

Use the Medio.EventApi.extras method to gain access to the singleton instance of this class.


Medio.MedioEventExtras.logPurchaseEvent

boolean logPurchaseEvent(itemId, unitPrice, currency, isCurrencyVirtual, quantity, options, paramsMap)

This method logs an event indicating that the user purchased an item in the application.

Parameters:

  • itemId: Your identifier for the item such as Stock Keeping Unit (SKU).
  • unitPrice: The price of the purchased item.
  • quantity: The quantity of the items purchased.
  • isCurrencyVirtual: Pass true indicate that the item was purchased with virtual currency units, false otherwise.
  • currency: The ISO 4217 alphabetic currency code. Use the constants provided in the Medio.MedioEventExtras class. For example, use the constant Medio.MedioEventExtras.Currency_USD for US Dollars. When logging purchases using virtual currency (isCurrencyVirtual == true), you may specify any string as a virtual currency code.
  • options: A reference to an optional Medio.LogPurchaseOptions object specifying additional information about the purchase. Pass null if you don’t want to include these options.
  • paramsMap: A map of key-value pairs corresponding to the event being logged. The maximum number of key-value pairs is 255. This parameter can be null. The length of each key should be less than 64 characters. The keys should not start with “__” and should not have “=” anywhere in the name. Any nil keys will be ignored, while null values will be converted to a string with a value of “null”.

Returns:
true if the event was logged successfully, false otherwise.


Medio.MedioEventExtras.createLogPurchaseOptions

Object createLogPurchaseOptions()

Creates an empty instance of a Medio.LogPurhaseOptions object.

Returns:
An empty instance of a Medio.LogPurhaseOptions object.


Medio.MedioEventExtras.openPurchaseCart

void openPurchaseCart()

Purchases logged after calling this method will be considered to be part of the same transaction.


Medio.MedioEventExtras.closePurchaseCart

void closePurchaseCart()

Closes the current purchase cart. This method ‘closes’ the transaction after previously calling Medio.MedioEventExtras.openPurchaseCart. Purchases logged after calling this method are not considered as part of the previous transaction.


Medio.MedioEventExtras.logEarnEvent

boolean logEarnEvent(earnAmount, currency, options, paramsMap)

This method logs an event indicating that your application earned revenue as a result of a user action.

Parameters:

  • amount: The amount of revenue earned.
  • currency: The ISO 4217 alphabetic currency code. Use the constants provided in the Medio.MedioEventExtras class. For example, use the constant Medio.MedioEventExtras.Currency_USD for US Dollars.
  • options: A reference to an optional LogEarnOptions object specifying additional information about the event. Pass null if you don’t want to include these options.
  • paramsMap: A map of key-value pairs corresponding to the event being logged. The maximum number of key-value pairs is 255. This parameter can be nil. The length of each key should be less than 64 characters. The keys should not start with “__” and should not have “=” anywhere in the name. Any null keys will be ignored, while null values will be converted to a string with a value of “null”.


Medio.MedioEventExtras.createLogEarnOptions

Object createLogEarnOptions()

Creates an empty instance of a Medio.LogEarnOptions object.

Returns:
An empty instance of a Medio.LogEarnOptions object.

Medio.LogPurchaseOptions

Create an instance of this type by calling Medio.MedioEventExtras.createLogPurchaseOptions.


Medio.LogPurchaseOptions.setItemCategoryTag

void setItemCategoryTag(itemCategoryTag)

Sets the category of the purchased item.

Parameters:

  • itemCategoryTag: The category to set.


Medio.LogPurchaseOptions.setItemType

void setItemType(itemType)

Sets the type of the item purchased. Pass null or one of the following constants to this parameter. If your item type does not match one of these constants, you may specify any string as your item type.

  • Medio.MedioEventExtras.PurchaseItemType_Consumable: The consumable item type. Use this type if users purchase the item each time it is needed.
  • Medio.MedioEventExtras.PurchaseItemType_NonConsumable: The non-consumable item type. Use this type if users purchase the item only once.
  • Medio.MedioEventExtras.PurchaseItemType_Merchandise: The merchandise item type. Use this type if the purchased item is physical merchandise.
  • Medio.MedioEventExtras.PurchaseItemType_VirtualCurrency: The virtual currency item type. Use this type if the purchased item is virtual currency.

Parameters:

  • itemType: The item type to set.


Medio.LogPurchaseOptions.setReferrer

void setReferrer(referrer)

Sets a referrer for the purchase. The referrer is a place within your application where the user came from before making the purchase.

Parameters:

  • referrer: The referrer to set.

Medio.LogEarnOptions

Create an instance of this type by calling Medio.MedioEventExtras.createLogEarnOptions.


Medio.LogEarnOptions.setEarnId

void setEarnId(earnId)

Sets your identifier for the earn event.

Parameters:

  • earnId: The earn ID to set.


Medio.LogPurchaseOptions.setEarnType

void setEarnType(earnType)

Sets the type of earned revenue.

Parameters:

  • earnType: The earn type to set.