Sign Up Login

HTML5 Integration Guide

Overview

The Localytics HTML5 library is a JavaScript file which is to be included in a web based application which will be rendered on a mobile device. This includes applications delivered via the respective application markets as well as direct linking from another site.

Notes and Updating from Previous Versions

At this time iOS is fully supported and large majority of Android devices are supported. In cases where the device is not supported the library will fail silently and not impact the web application.

If you are updating from prior to version 2.4 note there are now changes to the implementation, notably the removal of localyticsSession.init()- this step is now part of assigning the localyticsSessiion variable.

Ten Minute Instrumentation Instructions

  • 1) Log into your Localytics account or create an account if you do not already have one.

  • 2) In your account, create a new application and copy the application key.

  • 3) Download the HTML5 Library as Source.

  • 4) Copy the Localytics JavaScript file to your local web server and then reference the JavaScript file that is on your site on every page of your mobile web application. This needs to be done before any Localytics functions are called: 
    <script language="JavaScript" type="text/javascript" src=”/path/to/localytics.js”></script>

  • 5) On every page load, initialize the Localytics object, open the session, and upload the data. Calling open when a session is already open causes it to rejoin the existing open session. 
    <script language="JavaScript" type="text/javascript">          
            var localyticsSession = LocalyticsSession("APP KEY FROM STEP 2");
            localyticsSession.open();
            localyticsSession.upload();

</script>

  • 6) Navigate through the mobile web application and then visit the Localytics reporting interface to ensure data is being uploaded.

    • Events (Recommended)

    Unsure what events to tag? Check our Event Recommendations

    Anywhere in your application where an interesting event occurs you may tag it by adding the following line of code: 

    … existing JavaScript action...
localyticsSession.tagEvent("Event Name");
    where “Interesting Event” is a string describing the event. It is recommended that you read the Tagging section in the Developer’s Integration Guide in order to get the most value out of your tags.

    For some events, it may be interesting to collect additional data about the event. Such as how many lives the player has, or what the last action the user took was before clicking on an advertisement. This is accomplished with the second form of tagEvent, which takes a hash of attribute name / value pairs: 

      localyticsSession.tagEvent("Event Name", {“AttributeName”: attributevalue, “AttributeName2”: attributevalue2});
    For example, recording an article view in a news application might look like this: 
    localyticsSession.tagEvent("Article View", {“Page Name”:Baseball-Headlines , “Section”: “sports”});
    It is recommended that you read the Event Attributes section in the Developer’s Integration Guide in order to get the most value out of your attributes.

    Important Note:

    Make sure never to upload data from a continuous set or from user-generated values. Consider tagging a file transfer event with the file size and name. If the file can be any size this will cause many buckets to be created on our server. When you look at the data in the charts, there will be many charts each with only a few results and the data will be in-actionable. Instead, it is necessary to bucket this data into groups such as “0 to 1K”, “1K to 50K”, etc. Similarly, if you allow users to create their own name for the file, you will have a list of thousands of unique file names that are also not useful to view in the dashboard. See our blogpost for an example.


    Screen Flows

    Whenever a page is loaded it can be tagged using the tagScreen API. This should be called after the open for each page. Names should be statically defined to avoid recording too many values which will make the charts hard to get value out of. Note: localyticsSession.close() needs to be called in order for the Screen data to be uploaded. Like events, it is also not recommended to name each screen dynamically. For example, a screen displaying an article should be tagged simply as “Article” instead of the title of the article. For example, this is the screen tag for the Article View: 

    localyticsSession.tagScreen(“Article View”);

    Options

    The following options may be passed to to the assignment of the localyticsSession variable:

    • appVersion
    • networkCarrier
    • polling
    • uploadTimeout
    • sessionTimeoutSeconds
    • storage
    • logger
    The Localytics HTML5 library does not have access to some of the default attributes found in other versions of the Localytics SDK libraries. If your application has knowledge of these values, you may pass them in here:
    • appVersion: string; your application’s version (default: undefined)
    • networkCarrier: string; the curent device’s carrier (default: undefined)
    The rest of the options are for configuration and debugging:
    • polling: number; frequency in milliseconds that Localytics polls for the end of a session (default: 10,000)
    • uploadTimeout: number; upload timeout in milliseconds (default: 60,000)
    • sessionTimeoutSeconds: number; timeout in seconds until Localytics marks the session as closed (default: 30)
    • storage: number; maximum number of characters Localytics is allowed to use from the localStorage (default: 100,000)
    • logger: boolean; whether to enable console logging (default: false)

    Example with parameters

    var options = {  
 appVersion: "v1.5",  
 networkCarrier: "AT&T"
 polling: 10000,  
 uploadTimeout: 60000,
 sessionTimeoutSeconds: 30,
 storage: 100000,  
 logger: true};

var localyticsSession = LocalyticsSession(APP_KEY_FROM_STEP_2, options);

    Common Mistakes

    Ready to ship? Check our list of common integration mistakes to ensure you get the best reporting experience possible.

    If you are using this library for a BB10 app, please note you must edit the src variable within the jsonpSend function to add http:// in front of the address.

    Advanced Features (Premium and Enterprise)

    Please see our Advanced Features guide for help on implementing some of our latest features.