Javascript Agent

Use the Javascript Agent to post events to Loggr from your web application.

Installing
How To Use
Reading Events
Posting Events
Trapping and Posting Error Events
Tracking Users

Installing

Installation is simple. Link to the loggr.min.js file on our server.

<script type="text/javascript" src="http://api.loggr.net/1/loggr.min.js"></script>

If you'd like to make your coding a little easier, you can add your LOGKEY and APIKEY to the script tag. This will create a global Log instance that you can start posting events from instead of having to initialize one in your Javascritp code.

<script type="text/javascript" src="http://api.loggr.net/1/loggr.min.js?l=testlog&a=48ce330a6c334be7b287e28e35a011ea"></script>

Note

We keep the latest copy of our javascript files (including the minified version) on GitHub (https://github.com/loggr/loggr-js). In some cases you may need to modify the code to make it work better for you. Feel free to do so. Maybe write a blog post to share how you improved it.


top

How To Use

This library can read and post events. The first thing you need to do is get a reference to a log using the LOGKEY and APIKEY which can be found thru loggr.net

var log = Loggr.logs.get("YOUR-LOGKEY", "YOUR-APIKEY");

If you added your LOGKEY and APIKEY to your script tag (like the second option above), you can skip the preceding line of code and instead use the global Loggr.Log instance to post events.

var log = Loggr.Log;

Once you have a reference to your log, you can follow the instructions below to read and write events to your log. The following examples will assume you have a log variable instantiated like one of the options above.

top

Reading Events

There are 3 methods for reading events: get(), query() and getData(). You can try this out here: http://go.loggr.net/jsread

events.get() returns a single event given an event id:

log.events.get(id, function (e) {
    alert(e.text);
}

events.query() executes a Loggr Query Language (LQL) statement and returns the results:

log.events.query("GET events TAKE 10 SORT created DESC", function (es) {
    alert(es.length);
}

Check out the Events Resource page to see an example of what is returned in the previous two calls.

events.getData() returns a the data for a given event id:

log.events.getData(id, function (data) {
    alert(data);
}

In the getData() call, the data returned is a string.

top

Posting Events

With a log reference you can create and post events using a fluent event wrapper. You can try this out here: http://go.loggr.net/jspost

log.events.createEvent().text("this is text").post()

log.events.createEvent()
    .text("my first event")
    .link("http://loggr.net")
    .tags("tag1 tag2")
    .source("web1")
	.user(sUsername)
    .value(35.50)
    .data("<b>user-agent:</b> {0}<br/><b>on:</b> {1}", navigator.userAgent, new Date())
    .dataType(Loggr.dataType.html)
    .geo(40.1203, -76.2944)
    .post();

The text, link, source and data methods can work like the C sprintf function:

log.events.createEvent().text("the date is {0} and the time is {1}", new Date().toDateString(), new Date().toTimeString());

Those methods will also replace $$ with the previous value:

log.events.createEvent().text("foo").text("$$bar") // will output "foobar" for the text

The tags method can accept an array of string, a space-delimited string, or multiple string arguments:

.tags(new Array("tag1", "tag2"), "tag3")
.tags("tag1 tag2", "tag3")

The text, tags and data methods also have corresponding append methods, which append values. addText(), addTags(), addData() take the same arguments that their setters do.

When settings data, you can specify if the data is to be displayed as HTML or Plain Text using the .dataType() method (plaintext is default)

.dataType(Loggr.dataType.html) or .dataType(Loggr.dataType.plaintext)

When setting geo, you can specify a latitude and longitude, or a prefixed value like:

.geo(40.1203, -76.2944)
.geo("40.1203, -76.2944")
.geo("ip:274.65.485.231")

top

Trapping and Posting Error Events

In some cases it is helpful to automatically trap errors and have events posted to Loggr. Javascript has a global event (window.onerror) that gets fired when a runtime error occurs. Use the code below to handle that event and post an error to Loggr.

window.onerror = function (msg, url, line) {
    var data = "Message: " + msg + "<br>";
    data += "URL: " + url + "<br>";
    data += "Line: " + line + "<br>";
    data += "Platform: " + navigator.platform + "<br>";
    data += "User Agent: " + navigator.userAgent + "<br>";
    log.events.createEvent()
        .text("Runtime error: " + msg)
        .tags("error")
        .user(appUserName)
        .dataType(Loggr.dataType.html)
        .data(data)
        .post();
}

Keep in mind this will hide the error from the end-user, so you may want to show a pretty version of the error to your user and disable this code for debugging.

top

Tracking Users

It's also really helpful to be able to see details and activity history for the users being assigned to an event. To do that from Javascript you just need to make a simple call.

We actually recommend putting a call like this on every web page so you can see where the user was at any given time. You also be able to re-trace the steps a user took to get to a certain point.

var username = "USERNAME";
var emailAddress = "EMAILADDRESS";
Loggr.Log.trackUser(username, emailAddress);

Make sure you set the 'username' and 'emailAddress' variables to the current user's actual values.

You can also send a 3rd argument to the trackUser() method which would be the "page" the user is viewing. If you don't specify it, the current page's URL will automatically be used.

var username = "USERNAME";
var emailAddress = "EMAILADDRESS";
var path = window.location.pathname + window.location.search;
Loggr.Log.trackUser(username, emailAddress, path);

If you want to track the user on every page just insert the following code before the closing BODY tag for each web page of your app.

<script type="text/javascript">
    var username = "USERNAME";
    var emailAddress = "EMAILADDRESS";
    Loggr.Log.trackUser(username, emailAddress, window.location.pathname + window.location.search);
</script>

top