Follow

Integrating the Apmetrix JavaScript SDK

The following simple steps explain how to integrate our JavaScript SDK into your website.

Table of Content:

Apmetrix JavaScript Integration

Apmetrix JavaScript SDK Functions

Integrating the Apmetrix JavaScript SDK

The Apmetrix Javascript SDK provides powerful real-time metrics usage by recording and processing a stream of HTTP requests sent from visitors to our Apmetrix tracking gateway.

Just by simply adding the properly configured Javascript SDK, you can track 90% of your analytics… Visits, Time on Site, retention, sessions, device info, etc… (so in effect, a single line of code and you’re up and running).

Below we’ll discuss how to do extra logging per page, and also Custom Events.

Required JavaScript files

The JavaScript SDK module uses a single JavaScript file: Apmetrix.js.

JavaScript file required configuration

The Apmetrix.js file contains a configuration section (at the bottom of the file) which should be reviewed before the file is uploaded. The following fields should be updated to match the desired configuration:

// Put your appDataset, appVersion and appUnifier here...

Apmetrix_t['dataset'] = 123456
Apmetrix_t['appVersion'] = "0.0.1"
Apmetrix_t['unifier'] = "123456ABCDEFG123456"

Depending on whether you're using a standard Browser or building this SDK into an App, you may need to comment in one of the lines below

// Set the gateway protocol
// natural web documents can switch on the fly (between http: and https:) (this is the default and recommended method)
Apmetrix_t['protocol'] = document.location.protocol;

// WinJS and other apps may need to over-ride this otherwise end up with ms-appx:, which is not valid to our gateway

// valid entries are http: and https:
// Apmetrix_t['protocol'] = "https:";

NOTE: The Dataset ID and Unifier are NOT usernames or passwords. These are used as a marker to internally direct traffic within our system. There is no security issue with this information appearing upon viewing source in a web browser.

The sections marked in BOLD above must be updated for all deployments. The Dataset ID/Unifier should be updated to match the Dataset that you’d like to collect data for. You can look up the correct Dataset ID/Unifier through the web-based reporting interface. Go to the Account administration under the Tools menu and click on the desired Dataset. The Dataset ID and Unifier will be shown in the Dataset properties window.

You may also optionally set the cookie domain to match the web site on which the tag is going to be deployed. If this value is set incorrectly, no cookies can be set and visitor profiles and session management won’t work for the site. Set the domain to either the full domain of the website or a parent domain. For a web site hosted at http://www.test.com, the correct cookie domains can be either www.test.com or test.com. By default, the code will attempt to determine the correct domain based on the page URL.

// Cookie domain
Apmetrix_t['domain'] = "www.website.com";

Referencing the JavaScript files

The JavaScript file needs to be loaded on every page that should be tracked. You can load the SDK by inserting a simple <script> reference on the page: (I usually put it at the bottom of the page, but it can be anywhere).

When a page loads the Javascript it runs automatically… any variables you want to send MUST be defined before the Javascript loads.

<script language="javascript1.1" type="text/javascript" src="apmetrix.js"></script>

Understanding the Apmetrix Functions

*NOTE: All these functions and examples can be found in the default.html file

Adding Custom Events

Call the following method to log custom events.

*IMPORTANT NOTE: The logEvent function params are unique since they must be passed in as an Array

Apmetrix_t.logEvent([table, dimenstions]);

table

Predefined value for the type of Apmetrix_t.CustomEvent

dimensions

Variable length comma delimited list of custom event dimensions.

 

Note: The platform has the ability to take in up to 25 string dimensions (maximum) and 4 metric dimensions (maximum).

Adding custom events to your game or app is hugely beneficial and highly encouraged as it allows you to track many types of events and actions that users and applications generate. Our platform allows you to pass in an unlimited number of these events and track them in many different ways. While this functionality is extremely powerful, it can also be very unwieldy if some best practices are not thought of or contemplated in advance. While you can of course create as many dimensions as you like (up to 24 in fact), we have suggested a logical way using 4 dimensions which may make it easier to create and and report on your custom data.

 

Integer values for the table parameter are as follows:

(1) Apmetrix_t.UN_GROUPED_TABLE

The dimension data is ungrouped

(2) Apmetrix_t.USERS_TABLE

The dimension data pertains to the user

(3) Apmetrix_t.APPS_TABLE

The dimension data pertains to the application

(4) Apmetrix_t.TRACK_TABLE

The dimension data pertains to the location

(9) Apmetrix_t.FTUE_TABLE

The dimension data pertains to the first time user experience

(10) Apmetrix_t.ENGAGE_TABLE

The dimension data pertains to the user engagement

 

As a game or app can have many such custom events, it is important to logically categorize your local application variables as you would logically think such an event should be tracked. A suggested structure (at least for the first four dimensions) would be as follows;

  • Verb – What event is occurring such as “crashed”, “invited”, “fired”, “damaged” etc.
  • Object – What action is occurring on what object such as “car”, “friend”, “house” etc.
  • Location – Where did such an event occur? It is useful to think of this within the context of your game or app as each is different based on context. For example; for an adventure game you may want to list the map or level where the event occurred. For a racing game, perhaps the track, or for a puzzle game, the name of the puzzle or level. Think in terms of relevant location data you’d need to know.
  • Value – This is additional information in the form of a string you may wish to pass in depending on the specific event you are tracking. For example; you may want to pass in the time for the car crashed, determine whether a condition was True or False, etc.
  • Numerical Value - This is additional information you may wish to pass in depending on whether or not you need to pass in a number (i.e. if you want to track currency or economy flows such as "Primary Currency at Session Start", Primary Currency Earned", "Primary Currency Spent", "Primary Currency at Session End" ).

Important Notes:

Since the system defaults to treating incoming data as strings, you will need to include the “#” symbol in front of your metric data so the system recognizes it as a numerical value.

Also note that since these are literal examples you will need to replace the parameter with the actual local game variable you wish to pass in to the platform so as to appropriately reflect your own data structure.

*IMPORTANT NOTE: The logEvent function params are unique since they must be passed in as an Array

CUSTOM LOG EVENT EXAMPLE:

Apmetrix_t.logEvent([Apmetrix_t.APPS_TABLE, "verb", "object", "location", "value"]);

Below is a break down of how the dimensions and metrics are split up:

Dimension 1 - verb

Dimension 2 - object

Dimension 3 - location

Dimension 4 - value

Metric 1 - 1 (Metric 1 always has a value of one since it specifies how many times this event was called)

*IMPORTANT NOTE: The logEvent function params are unique since they must be passed in as an Array

CUSTOM LOG EVENT W/ METRIC EXAMPLE:

Apmetrix_t.logEvent([Apmetrix_t.APPS_TABLE, "verb", "", "location", "#100", "#200", "#300"]);

Below is a break down of how the dimensions and metrics are split up:

Dimension 1 - verb

Dimension 2 - (In this case since dimension 2 is an empty string nothing is passed for dimension 2)

Dimension 3 - location

Metric 1 - 1 (Metric 1 does not need to be passed in by the developer. It always has a value of one since it specifies how many times this event was called)

Metric 2 - 100

Metric 3 - 200

Metric 4 - 200

Generating Manual Server Calls

In addition to the automatic page view call that is generated when the page loads, you can generate additional server calls in response to events on the page. To do so, execute the following JavaScript call:

 

<script language="javascript1.1">

var parameters = new Object();

Apmetrix_t.sendReq(parameters);

</script>



Any parameters that you’d like to send to the server should be attached to the parameters-object.

Passing Parameters to the Tag

Parameters can be passed in three ways. For a manual server call, you can pass parameters through the first argument to the sendReq() call. This is an object which can contain any number of properties. Alternatively you can use an array and pass it to the logEvent() call. This array contains up to 25 dimensions and 20 metrics along with a corresponding table number (which are pre-defined).
You can also pass parameters to the main pageview request that occurs when the tag is loaded. To do so, you’ll need to add parameters to the “pv” (page variables) object. If the object doesn’t exist on the page, you’ll need to create it before you can add parameters.

This can all be done in a single step:

<script>var pv={ name:"My Custom Page Name" };</script>

 

or as separate steps throughout the page:

 

<script>var pv = new Object();</script>

<script>pv[“name”] = “My Custom Page Name”;</script>

The parameters must be set before the page tag is loaded.
You can also pass parameters to the main Event request that occurs when the tag is loaded. To do so, you’ll need to add parameters to the “event” array. If the array doesn’t exist on the page, you’ll need to create it before you can add parameters.

This can all be done in a single step:

<script>var event=[“FTURE_TABLE”, ‘verb’, ‘object’, ‘location’, ‘value’,’#45’];</script>

 

The parameters must be set before the page tag is loaded.
You may also use the logEvent(Array) function to track mouse events such as

OnMouseDown
<ahref=’#’ onmousedown=”Apmetrix_t.logEvent([Apmetrix_t.FTUE_TABLE, ‘Clicked’, ‘Login Button’, ‘Homepage’]);”>Login Button</a>

Page View

Any server call that contains a page name is considered a page view. You can initiate a manual page view from the tag by calling Apmetrix_t. pageView(<parameters>). The default configuration of the tag will also generate an automatic page view each time the tag loads.

Recognized Parameters

Parameter name

Description

Valid values

Multiple values?

Name

Page name override.

 

If no parameters are specified, the page title will be taken from the <title> tag of the page.

If no title tag exists, the page name will be left empty.

String value

No

p.a_1 – 10

Page level attributes

 

The page view request supports up to ten attributes that are passed in the p.a_1 – 10 variables.

String value

No

Custom Events

As your users move about your website you will be able to track their behavior by using the Apmetrix_t.logEvent(Array) function. Apmetrix allows you to pass in up to 25 dimensions (Non aggregate values) and 20 metrics (Automatically aggregated values) in addition to a table number (pre-defined tables). The logEvent Array is defined as:

Recognized Parameters

Parameter name

Description

Valid values

Multiple values?

Table

The pre-defined table names. You may use these as a String or as a pre-defined Integer. *NOTE: You may only use the Apmetrix_t.TABLE_NAME after you load the JS file.

 

If no table is specified the SDK will default to the Actions Table.

 

Pre-Defined Integer Values:

Apmetrix_t.OTHER_TABLE

Apmetrix_t.ACTIONS_TABLE

Apmetrix_t.APPS_TABLE

Apmetrix_t.TRACKS_TABLE

Apmetrix_t.FTUE_TABLE

Apmetrix_t.ENGAGE_TABLE

 

String Values:

"OTHER_TABLE"

"ACTIONS_TABLE"

"APPS_TABLE"

"TRACKS_TABLE"

"FTUE_TABLE"

"ENGAGE_TABLE"

 

Integer/String value

No

Event Details

Comma delimited list of metrics/dimensions.

 

Dimensions are denoted as “Verb”, “Object”.

Metrics are denoted as “#23”, “#50”.

 

Metrics and Dimensions can be intermixed. The SDK organizes them in chronological order.

 

EX:

Apmetrix_t.logEvent([Apmetrix_t.ACTIONS_TABLE, “Verb”, #45”, “Object”, “”, “#50”, “Value”]);

 

For more information about how LogEvent works please visit (Note: This is a generic functionality breakdown): http://support.apmetrix.com/hc/en-us/articles/204117429

String value

Yes

Page Groups & Page Group Path Tracking

Path tracking is done through page groups, which allows the discovery of navigational behavior as a group instead of a single instance. The page group tag passes instructions which carries information about the server call. Page group information is passed together, even non-page view information.

 

<script type="text/javascript">
pv["p.g.n"] = "Page group 1";
pv["p.g.c"] = "reset,record";
pv["p.g.ea_1"] = "Entry on page 1";
</script>

Recognized Parameters

Parameter name

Description

Valid values

Multiple values?

p.g.n

Page group name.

String value

No

p.g.ea_1-5

Page entry.

String value

 

p.g.ca_1-5

Page group completion.

String value

Yes

p.g.a_1-10

Page group attributes.

String value

No

p.g.c

Page group control.

Multiple instructions can be passed simultaneously using a comma delimited list of control instructions as the parameter values.

Control instructions:

Reset – resets the path by erasing prior steps in the path that may have been recorded. The current page becomes the first step in the path.

Delete – deletes the current path traversal and records nothing in the path metric.

Record – finalizes the path by recording the current steps in the metric. No further steps will be tracked for the path. This can be combined with Reset to finalize and record the current path and at the same time start a new path with the same page.

String value

 

Yes

Downloads

Downloads are typically tracked when the visitor initiates a download of some non-HTML site content, such as a PDF file or a downloadable archive. You can track downloads by attaching an onClick handler to the download hyperlink which calls the page tag through Apmetrix_t.sendReq() with the correct parameters attached in an object.

Recognized Parameters

Parameter name

Description

Valid values

Multiple values?

d.n

Download name.

 

If no parameters are specified, the page title will be taken from the <title> tag of the page.

 

If no title tag exists, the page name will be left empty.

 

String value

No

d.a_1 – 10

Download attributes

 

String value

No

Streaming Media

Streaming media tracking typically involves instrumenting a media player plugin such as a Flash-based media player. Events should be dispatched as the visitor interacts with media player and as the media rolls.

Recognized Parameters

Parameter name

Description

Valid values

Multiple values?

m.n

Media name

Name of the media clip that is currently playing.

String value

No

m.a_1 – 10

Attributes of the current media clip such as format, title, author, etc.

String value

No

m.p

Media position.

The current position of the media. This parameter should contain the position as a percentage of the total clip (a range from 0-100 without %-character).

Numeric value in the range 0-100

No

m.s

Media state

The m.s variable is used to indicate the current media state and can contain: start, complete, pause, resume, rewind, forward, and skip.

String value enumeration.

 

Valid values:

 

start, complete, pause, resume, rewind, forward, skip

No

Page Assets

Page assets are modular sub-elements of a page such as a login box, a banner, status messages, and other elements that can appear on more than one page. They are most commonly sent together with the initial page view request of the page. You can pass more than one-page asset per request by comma-delimiting the values. A page asset can be either viewed or interacted with (clicked on)

Recognized Parameters

Parameter name

Description

Valid values

Multiple values?

pa.n

Page asset name

 

String value

Yes

pa.a_1 – 10

Page asset attributes

 

String value

Yes

pa.a

Page asset action

 

The action can either be “v” for view, or “c” (for click). This parameter supports multiple comma-delimited entries. If no value is present, it is defaulted to “v”.

String value enumeration

 

Valid values:

 

v, c

Yes

Site Actions

Site actions can model any actions taken by the visitor on the web site such as logging in, logging out, using internal search, etc. If the site action is a step-based process, you can flag the site action as initiated or completed as the visitor moves through the completion process.

Recognized Parameters

Parameter name

Description

Valid values

Multiple values?

a.n

Site action name

String value

No

a.a_1 – 10

Site action attributes

String value

No

a.a

Site action state

 

The action can either be “i” for initiated, or “c” (for completed). If no value is present, it is defaulted to “c”.

String value enumeration

 

Valid values:

 

i, c

No

Campaign Responses

Campaign responses are tracked in campaign sub-objects. The notation is shown below:

 

<script>var pv={ cmp:[{id:"Campaign id 1", a_1: "Campaign attribute 1", exp:"60"}] };</script>

<script>pv.cmp.push({id:"Campaign id 2", a_1: "Campaign attribute 2", exp:"2592000", c:"11"});</script>

Recognized Parameters

Parameter name

Description

Valid values

Multiple values?

cmp.id

The campaign name. If passed on the page URL, the name is “cmp_id”.

String value

Yes

cmp.a_1 – 10

Campaign response attributes.

 

You can attach up to ten attributes to each campaign response.

String value

Yes

cmp.c

Campaign response cost

 

This is the campaign cost. The value shouldn’t contain any fractional numbers or punctuation.

Numeric value

Yes

cmp.exp

Campaign expiration

 

If set, the campaign response will expire after the specified amount of time has passed. The value is expressed in seconds. To force a response to expire after one day, enter 60*60*24 = 86400. If no value is passed the response will never expire.

Numeric value, expressed in seconds

Yes

Goals/Campaign Conversions

Goals or campaign conversions are tracked as a sub-object. The notation is shown below:

 

<script>var pv={ goal:{id:"Conversion 1", v:"10", cmp:"last", a_4: "Goal Attribute 4"} };</script>

Recognized Parameters

Parameter name

Description

Valid values

Multiple values?

goal.id

Goal name

String value

No

goal.a_1 – 10

Goal attributes

 

You can attach up to ten attributes to each goal.

 

String value

No

goal.v

Goal value

 

The monetary value of reaching the goal.

 

The value shouldn’t contain any fractional numbers or punctuation.

Numeric value

No

goal.cmp

Campaign conversion control

 

You can control which (if any) campaigns should be converted upon reaching the goal. Valid values include:

 

“first” – The first responded to campaign is converted.

 

“last” – The most recently responded to campaign is converted.

 

“all” – All campaigns are converted.

 

Numeric value, expressed in seconds

No

goal.

match_key,

 

 

 

 

 

goal.

match_value

You can use match_key and match_value to achieve more fine grained control over which campaigns are converted.

 

The match_key variable should contain the name of a campaign variable, such as id, a_1, or a_2.

 

The value of the variable is compared against match_value and any campaigns with matching variables are converted.

 

These variables function independently of the value of goal.cmp.

String values

No

Link Tracking

Automatic link click tracking can be enabled by setting the link tracking flag the apmetrix_c.js file:

 

// Automatic link click tracking: 1 = on, 0 = off
Apmetrix_t['link_tracking'] = 1;



When automatic link tracking is turned on, the page tag will attach an on-click handler to each link on the page. When a visitor clicks a link, the click handler will send a request to the Apmetrix servers indicating that the link was clicked.
When automatic link tracking is turned off, you can initiate link click events manually by attaching onclick-handlers to the anchor tags.
The automatic link tracking code will not populate any attributes for the links.
Automatic link tracking will pick up the name of the link first from the text attribute of the link, secondly from the alt-text of the first HTML child of the link, and thirdly by giving the link a static named based on its position in the page.

Recognized Parameters

Parameter name

Description

Valid values

Multiple values?

lc.n

Link name

String value

No

lc.a_1-10

Link attributes

String value

No

lc.u

Link URL

String value

No

Form Tracking

Automatic form analysis can be enabled by setting the form tracking flag the apmetrix.js file:

 

// Automatic form tracking: 1 = on, 0 = off
Apmetrix_t['form_tracking'] = 1;



When automatic form tracking is turned on, the page tag will enumerate each form on the page and include form information in the main page view request.
The form’s name-attribute will primarily be used as the form name. If a name isn’t available, the form id-attribute is used instead. If neither attribute is specified, the form will be named “Unnamed form X” where X is the form’s position in the list of forms on the page.
Form tracking primarily tracks the relation between form views, submissions, and errors.
Since form errors can take a wide variety of forms, they can’t be automatically detected by the page tag and it’s the responsibility of the implementer to pass any error messages to the tag.
If automatic form tracking is turned off, form events can be passed to the tag through the recognized parameters. This can sometimes be desirable to provide more granular control of the implementation.
When automatic form tracking is turned on, the only parameter that needs to be passed in to the tag is fs.e (form submission error message) on a page refresh. You can also pass form submission information as part of JavaScript validation on the page.
The automatic form tracking code will not populate any attributes for the forms.
There are some important special cases in the form tracking that it is useful to be aware of:
• A form submission is tracked as a form interaction. This is done because some forms don’t require any direct user input to submit and form submissions could otherwise be greater than interactions.
• Form errors are attributed to the last form interaction or submission. This is done because it’s possible for client-side validation to trigger error messages without the form actually being submitted (and this ensures that errors are at least less than interactions)
• Form interactions are triggered by a form change or key press event. Only one form interaction is tracked per page load.
• A form start is tracked every time the user interacts with a different form compared to the last form interaction. If a multi-step form should be tracked as a single entity, it should be given the same name throughout the process. You can use the form attributes to track process through the steps.

Recognized Parameters

Parameter name

Description

Valid values

Multiple values?

fv.n

Forms viewed (name)

 

String value

Yes

fv.a_1 – 10

Forms viewed (attributes)

 

String value

Yes

fi.n

Submitted interaction (name)

String value

No

fi.a_1-10

Submitted interaction (attributes)

String value

No

fs.n

Submitted form (name)

String value

No

fs.a_1-10

Submitted form (attributes)

String value

No

fs.e

Submission error message. If no message is specified, the form is assumed to have been submitted successfully. The error will be attributed to the form specified in fs.n if that parameter is present. If no form name is specified, it will be attributed to the last form that was submitted.

String value

No

HTTP 404 and 500 Error Tracking

HTTP 404 and 500 error tracking can be enabled by locating the custom 404 and 500 error pages on the web server or creating these custom pages if they do not exist, and then on those pages populating the nf.url parameter with the originally requested URL:

 

<script type = “text/javascript”>
var pv = new Object();
pv[“nf.url”] = “http://www.website.com/prodducts.html”;
pv[“nf.a_1”] = “The URL has a misspelling of the word products and the page could not be found”;
</script>

 

The procedure for populating the nf.url parameter with the originally requested URL will vary depending on the server and content management system.

Recognized Parameters

Parameter name

Description

Valid values

Multiple values?

nf.url

Originally requested URL

String value

No

nf.a_1-10

Error attributes

String value

No

Tracking Visitors who have JavaScript Disabled or Unavailable

In most cases you will want to ensure that visitors who have JavaScript disabled or unavailable are still tracked. This is particularly important when it comes to visitors using mobile devices, as many mobile browsers currently on the market do not support JavaScript tagging.
Tracking visitors who have JavaScript disabled or unavailable can be enabled by using noscript code and embedding variables in a 1x1 img tag reference:

 

<noscript><img width=”1” height=”1” src=”http://gw.apmetrix.com/gw?g.r=i&g.d=100339&g.a=pv&g.y=ns&p.t=[INSERT_PAGENAME_HERE]”/></noscript>

 

Each variable needs to be URL encoded if it contains spaces or special characters. This is important particularly for the page name, which typically includes embedded spaces.
Note: Almost any other tag can be used by prefixing the tag with "pv." followed by the tag itself.

Recognized Parameters

Parameter name

Description

Valid values

Multiple values?

g.r

Gateway return of a 1x1 transparent gif image

 

 

If set to “i”, the gateway will return a 1x1 transparent gif image. If not set, the gateway will not return an image.

 

String value

enumeration

 

Valid values:

 

i

 

No

g.d

Dataset id

This is the same as typically specified in apmetrix.js.

 

Numeric value

No

g.u

Unifier

This is the same as typically specified in apmetrix.js.

 

Numeric value

No

g.a

Action type

 

 

If set to “pv”, indicates that the current action is a page view.

String value

enumeration

 

Valid values:

 

pv

 

No

g.y

Noscript request identifier

 

 

 

 

This should be set to “ns”.

String value

enumeration

 

Valid values:

 

ns

No

 

 

p.t

Page title

This is typically generated from the server in the no-script case.

String value

No

ApTrak

Call the following method to track user interaction, logging the coordinates for a specified event at a specified location or screen:

Apmetrix_t.ApTrak(event, location, [coordinates]);

 

ApTrak EXAMPLE:

Apmetrix_t.ApTrak("touch", "screen1", [touchPos.x, touchPos.y]);

Event coordinates should be input in the following order:

X (required), Y (required), Z (optional) and W (optional)

In Application Purchases

- To log a purchase made with real currency (as opposed to virtual currency):

You will want to reference the In-App Purchase document for more details on In App Purchases.

This function ties to the In-App Purchases Table.

Function Call - when you want the converted cost to be generated based on:

  • the users IP address (to determine local currency) and
  • your country's currency (the country you specified when you created an account with Apmetrix) :
Apmetrix_t.inApPurchase(quantity, item, location, itemCost);

or ...

Function Call - when you want the converted cost to be generated based on local and converted currencies you provide:

Apmetrix_t.inApPurchase(quantity, item, location, itemCost, localCurrency);

where

quantity

identifies the amount of items purchased

item

identifies the item(s) that were purchased

location

identifies where within the application the user purchased the items

itemCost

identifies the cost that the user purchased the item(s) for

localCurrency

currency that the user purchased the items with. It is suggested to use the pre-defined values for local currency to avoid errors in exchange rate generation. These pre-defined values are shown in In-App Purchase document.

 

In Application Purchase Code Examples:

Following are some examples that demonstrate use of the inApPurchase() function using both function call options.

If you do not know the local currency or what currency you want to convert to use this example. We will do the conversion server side using data from your App Setup on the Apmetrix Dashboard.

Apmetrix_t.inApPurchase(1, "100 Gem Package", "Main Screen", 2.25);

If you know the local currency go ahead and use this example

Apmetrix_t.inApPurchase(1, "100 Gem Package", "Main Screen, 2.25, EUR);

 

Virtual Item Transaction Tracking

Call the following method to log virtual item transactions.

Apmetrix_t.virtualItem(transaction, qty, itemType, location, primaryCurrency);
Apmetrix_t.virtualItem(transaction, qty, itemType, location, primaryCurrency, secondaryCurrency);
Apmetrix_t.virtualItem(transaction, qty, itemType, location, primaryCurrency, secondaryCurrency, tertiaryCurrency);

Where

transaction

identifies the transaction that was made ("Bought", "Sold", "Traded", etc.)

quantity

identifies the amount of items involved in the transaction

type

identifies the type of item(s) involved in the transaction

location

identifies where within the application the transaction took place

currencyAmounts

a list of currency amounts for the item(s). Up to 3 different denominations can be specified but denominations must be kept in the same order each time this function is called. For example, if this function is called once with a primary currency amount and secondary currency amount then each call to this function must have at least a primary currency amount even if it is 0.

 

Use this function when you want to track the flow of in-game items & in-game currency. This function ties to two tables (Virtual Currency & Virtual Items) on the Apmetrix Dashboard.

Examples:

This example shows 1 Wand of Hate was sold at the Evil Shop for 15 primaryCurrency, 20 secondaryCurrency and 5 tertiaryCurrency

Apmetrix_t.virtualItem("Sold", 1, "Wand of Hate", "Evil Shop", 15, 20, 5);

This example shows 1 Wand of Luck was bought at the Evil Shop for 15 primaryCurrency, 20 secondaryCurrency

Apmetrix_t.virtualItem("Bought", 1, "Wand of Luck", "Evil Shop", 15, 20);

This example shows 1 Wand of Greed was pawned at the Evil Shop for 15 primaryCurrency

Apmetrix_t.virtualItem("Pawned", 1, "Wand of Greed", "Evil Shop", 15);

Offer Tracking

Call the following method to log offers that are presented/accepted/declined.

Apmetrix_t.offer(transaction, offerType, location);

Where

transaction

identifies the transaction that was made and has the following meanings:

Apmetrix_t.PRESENTED- used to denote an offer presented to the user

Apmetrix_t.ACCEPTED - used to denote an offer accepted by the user

Apmetrix_t.DECLINED - used to denote an offer declined by the user

offer

identifying the actual offer "30% off weekend sale", "10% off all Gems", etc

location

identifies where within the application the offer was presented, accepted or declined. "Main Menu", "Pay To Rush", "Cash Shop", etc

This function ties to the Offers Table on the Apmetrix Dashboard.

Examples:

Use this example when you want to track an offer that was Presented to the user

Apmetrix_t.offer(Apmetrix_t.PRESENTED, "Weekend Sale 20% Offer", "main menu");

Use this example when you want to track an offer that was Accepted by the user

Apmetrix_t.offer(Apmetrix_t.ACCEPTED, "Weekend Sale 20% Offer", "payToRush");

Use this example when you want to track an offer that was Declined by the user

Apmetrix_t.offer(Apmetrix_t.DECLINED, "Weekend Sale 20% Offer", "cash shop");

Start Timer

Call the following method to start a new timer:

Apmetrix_t.startTimer(timerName);

Where timerName is the name of the timer. If you start a timer and that timer already exists then the system will override the existing timer.

Ex:

Apmetrix_t.startTimer("Test Timer");

The timer system will automatically pause all active timers when your app is in the background and resume all paused timers when your app is in the foreground.

 

Stop Timer

Call the following method in the to stop an existing timer:

Apmetrix_t.stopTimer(string timerName);

Where timerName is the name of the existing timer. The system will only stop timers that exist.

Ex:

Apmetrix_t.stopTimer("Test Timer");

To better understand Timers it is recommended that you view the article on timers found here.

AppDidEnterBackground

The AppDidEnterBackground functions handles all required tasks that the SDK needs to perform when your application enters the background. For Timer functions It is important that this method be called in the proper location within your application so that the duration for the timer events you have started are accurate and only include the time the user is actively engaged with your application.

Call the following method to pause all active timers.

Apmetrix_t.appDidEnterBackground();

AppWillEnterForeground

The AppWillEnterForeground functions handles all required tasks that the SDK needs to perform when your application re-enters the foreground. For Timer functions It is important that this method be called in the proper location within your application so that the duration for the timer events you have started are accurate and only include the time the user is actively engaged with your application.

Call the following method to resume all paused timers.

Apmetrix_t.appWillEnterForeground();

 

Restart Session

Call the following method to restart a session that had previously been initialized but closed:

Apmetrix_t.restartSession();

Customer Tracking Code Example

The following is an example that demonstrates use of the setCustomerId: function where "Number 1 Fan" is the ID the customer is identified by:

Apmetrix_t.setCustomerId("123456-89076762");

 

Push Notification Code Example

The following is an example that demonstrates use of the sendDeviceToken("DEVICE TOKEN") which will send the device's push token to our servers

Apmetrix_t.sendDeviceToken("a29057n4uthqwgf3256fs32211");

End Session

Call the following method to close a session that is open:

Apmetrix_t.endSession();
Have more questions? Submit a request