You Are Currently Viewing: Customized Tracking, Logging Data Manually

Church Analytics's tracking code can be highly customized to interact with your web site in just the way you want, and used to track additional data. All of the customizations are available via a JSON object that you create called canalytics_custom.

You can also log data manually, either from Javascript events (which includes support for "onclick goals"), or from internal scripts - a feature unique to Church Analytics.

Some of the options here used to be unique variables that had to be declared seperately. We have added backwards compatibility into the tracking code so you don't need to change anything if you have already implemented some of these features.However, all of the new features, such as pageview_disable and overriding the page URL and title, are only available with the new format, so we recommend changing over to it.

canalytics_custom properties

Click on the name of any of these items to view the documentation for that specific item.

session - JSON - Attach custom data such as a username and an email address to a visitor session.

goal - JSON - Manually declare a goal as completed, and any revenue, if applicable.

href - string - Override the URL (path and query) being viewed. Only applies to page view actions.

title - string - Override the HTML page title. Only applies to page view actions.

timer - integer - Change the length of the pause timer for outbounds and downloads. Default is 500 (milliseconds).

timeout - integer - Change the length of time (in minutes) that a visitor will ping our servers while on a single page. Default is 20 (minutes).

no_cookies - boolean - Disable the cookies that our tracking code and our tracking servers set for your visitors. These cookies are only used to more accurately classify true unique visitors.

ping_disable - boolean - Our tracking code pings our servers periodically while a visitor is on a single page of your site, which helps us give a more accurate time-on-site value for each visitor. Use this option to disable the pinging.

advanced_disable - boolean - Disables the auto-tagging of outbound links and downloads. You will have to use CSS tagging or the canalytics.log() function to manually tag objects you want to track.

pageview_disable - boolean - Disables tracking a page view initial loading of the tracking code. Data will only be logged by manual calls to canalytics.log() or canalytics.goal(). Useful in scenarios where you only want data logged for certain events and actions.

You can declare canalytics_custom and the properties you want to use with a single command, or you can just define canalytics_custom as a generic JSON object and add the properties one at a time later. Which one you choose is up to you, although we do recommend the "one at a time" method. This is so that your logic for outputting this data doesn't have to be all in the same place, and so that you don't accidentally overwrite the entire object with a later call to it.

Each of these methods are shown in the examples below, and each accomplish the same end result: add a few session variables, change the pause timer to 200, and customize the page URL and title.

Example: One at a Time

<script type="text/javascript">
var canalytics_custom = {};
canalytics_custom.href = '/some/page?some=query';
canalytics_custom.title = 'Some page';
canalytics_custom.session = {
username: "bobjones",
group: "sales"
};
canalytics_custom.timer = 200;
</script>

<!-- your hypothetical tracking code, which must go after canalytics_custom -->
<script src="http://stats.churchanalytics.com/123.js" type="text/javascript"></script>

Example: All at Once

<script type="text/javascript">
var canalytics_custom = {
href: '/some/page?some=query',
title: 'Some page',
session: {
username: "bobjones",
group: "sales"
},
timer: 200
};
</script>

<!-- your hypothetical tracking code, which must go after canalytics_custom -->
<script src="http://stats.churchanalytics.com/123.js" type="text/javascript"></script>


IMPORTANT! The canalytics_custom object should only be declared ONE time within your entire HTML page. The examples below each declare it seperately, as they are standalone examples. If you are going to use more than one property, remember to only declare the canalytics_custom object the FIRST time!

Also, canalytics_custom and all of the properties you want to use must be defined before the tracking code is included on your web page. Otherwise, the tracking code will not see it!

canalytics_custom.session

The session property allows you to add your own data to a visitor session. This data will be stored in our database and accessible whenever you request the details of this session, whether that's through the web site itself, the API, third party widgets, or otherwise. When viewing a session on our web site, each custom value will have an icon next to it to easily distinguish your data from the standard data that we already track:



This is particularly useful if your web site has an account system that your users login to. When a user is logged in, you can attach their username and other information to their visitor session with this property. When you view your visitors list, the "username" key will be displayed in place of their IP address or organization/hostname, breathing life into your visitors and allowing you to quickly identify who is who. An unlimited number of key/value pairs can be declared, but we ask that you please keep it reasonable.

Custom data can be aggregated over multiple page views. For example if this user came from some kind of campaign you are running, you could attach that campaign ID or name (or both) to them on their initial landing. Then if they created an account and logged in to it a few minutes later, you could output their username as well, and that would be added to the session on our end. We only store each unique key once for any visitor session, so you don't have to worry about declaring the same value over and over again messing with the results.

Example:

<script type="text/javascript">
var canalytics_custom = {};
canalytics_custom.session = {
username: "bobjones",
group: "sales"
};
</script>

<!-- your hypothetical tracking code, which must go after canalytics_custom -->
<script src="http://stats.churchanalytics.com/js" type="text/javascript"></script>


How do you get the username or other data to output? Generally, you'll need access to the source code of your application to do that. Unfortunately, most hosted services, such as Typepad, don't let you do that. But there's still hope! When a visitor leaves a comment on most of these hosted blogs, the blog will save a few cookies that typically contain their name, email, and web site, so the next time the visitor leaves a comment they don't have to fill out that data again. You can extract that data with javascript, to attach their name to their session on Church Analytics!

The example below is for Typepad. WordPress cookie names are unique for each individual blog, as they are based on the domain name. To use with WordPress, leave a comment on your own blog and then look at the cookies for your domain. There should be one that starts with "comment_author_" and then a string of 32 random letters and numbers. This is the cookie name you would need to use for your blog.

<script type='text/javascript'>
function canalytics_get_cookie( name ) {
var ca = document.cookie.split(';');
for( var i in ca ) {
if( ca[i].indexOf( name+'=' ) != -1 ) return decodeURIComponent( ca[i].split('=')[1] );
}
return '';
}

var canalytics_custom = {};
canalytics_custom.session = { username: canalytics_get_cookie( 'typepadauthor' ) };
</script>

<!-- your hypothetical tracking code, which must go after canalytics_custom -->
<script src="http://stats.churchanalytics.com/js" type="text/javascript"></script>

canalytics_custom.goal

You can manually declare when a goal has succeeded using this property. You need to declare goals this way if you want to track revenue for them. You may also wish to use this method if the needs of the goal are too complex for our funnel system.

This property is a JSON object, which has 2 of its own properties: ID, and revenue. ID is required, revenue is optional. Note that ID must be declared in lowercase. Each goal has its own unique numeric ID in our database. The goal management page for any web site lists the ID for each goal next to the goal's name.

To track revenue, your code will need access to the value of the revenue, either through Javascript, cookies, or internally. You will need to talk to your shopping cart provider to discover how you can access and output this value.

Note that canalytics_custom.goal is NOT the same as the canalytics.goal() function. canalytics_custom.goal is for declaring a goal within the HTML of your page. canalytics.goal() is for declaring goals with Javascript events.

Example:

<script type="text/javascript">
var canalytics_custom = {};
canalytics_custom.goal = {
id: "10", // id is lowercase!
revenue: "49.95"
};
</script>

<!-- your hypothetical tracking code, which must go after canalytics_custom -->
<script src="http://stats.churchanalytics.com/js" type="text/javascript"></script>

canalytics_custom.href

If your URLs are complex with many variables, but you only want to track certain variables to make your content more consistent on Church Analytics, override it with this property. Note that this only applies for page view action types. Downloads, outbound links, and clicks are tracked differently.

Let's pretend the page being viewed is /items.php?id=123&name=Some+item&cart_id=456&campaign=Google. The only thing you probably care about is the ID. You would do this to override it:

<script type="text/javascript">
var canalytics_custom = {};
canalytics_custom.href = '/items.php?id=123';
</script>

<!-- your hypothetical tracking code, which must go after canalytics_custom -->
<script src="http://stats.churchanalytics.com/js" type="text/javascript"></script>

canalytics_custom.title

Use this property to override the HTML page title attribute. Note that this only applies for page view action types. Downloads, outbound links, and clicks are tracked differently.

Each unique URL for your web site can only have one unique title associated with it, which means any unique page URL that has already been tracked on Church Analytics cannot be changed with this property. However, there are plans to create an interface for you to change the titles of pages that are already stored in the database. This will be available in the future.

Example:

<script type="text/javascript">
var canalytics_custom = {};
canalytics_custom.title = 'Some page';
</script>

<!-- your hypothetical tracking code, which must go after canalytics_custom -->
<script src="http://stats.churchanalytics.com/js" type="text/javascript"></script>

canalytics_custom.timer

Tracking downloads and outbound links adds a slight delay from the time a visitor clicks the link to when their browser reacts to that click. This delay is to ensure there is time for their browser to talk to our servers before it follows the link. This effect is undesirable, but also unavoidable if you want reliable tracking.

The default value is 500 milliseconds (half a second). You can change this to any value you want, but the shorter time you choose, the greater chance there is that we won't receive this data from the visitor (unless these links open in a new browser window).

Example:

<script type="text/javascript">
var canalytics_custom = {};
canalytics_custom.timer = 250;
</script>

<!-- your hypothetical tracking code, which must go after canalytics_custom -->
<script src="http://stats.churchanalytics.com/js" type="text/javascript"></script>

canalytics_custom.timeout

Our tracking code automatically pings our servers when a visitor remains on a single page, so we can more accurately track the actual time they spend on your site. By default, after 20 minutes, this pinging will stop. Depending on the type of site you run, you may want to set this value higher or lower. You can set it to be anywhere from 5 minutes to 240 minutes (4 hours).

Example:

<script type="text/javascript">
var canalytics_custom = {};
canalytics_custom.timeout = 120; // 120 minutes = 2 hours
</script>

<!-- your hypothetical tracking code, which must go after canalytics_custom -->
<script src="http://stats.churchanalytics.com/js" type="text/javascript"></script>

canalytics_custom.no_cookies

Our tracking code uses cookies to better classify true unique visitors to your web site. If you don't want third party cookies on your web site, you can disable this feature by setting this value to 1. By doing so, uniques will instead be determined based on their IP address.

Example:

<script type="text/javascript">
var canalytics_custom = {};
canalytics_custom.no_cookies = 1;
</script>

<!-- your hypothetical tracking code, which must go after canalytics_custom -->
<script src="http://stats.churchanalytics.com/js" type="text/javascript"></script>

canalytics_custom.ping_disable

By default, our tracking code will periodically ping our tracking servers while a visitor is sitting on a single page, for up to 10 minutes. This helps us give you much more accurate time-on-site values for each visitor than most services offer, particularly for visitors who only have one page view. However, you can disable it if you wish, by using this option.

Example:

<script type="text/javascript">
var canalytics_custom = {};
canalytics_custom.ping_disable = 1;
</script>

<!-- your hypothetical tracking code, which must go after canalytics_custom -->
<script src="http://stats.churchanalytics.com/js" type="text/javascript"></script>

canalytics_custom.advanced_disable

When our tracking code is loaded on your web site, it automatically parses through all of the links on the current page and determines which ones are outbound links and file downloads. Then, when a user clicks on one of these, we can track it appropriately.

If you want to disable this automatic tagging for any reason, you can do that with this property. If you use this property, you can use canalytics.log() or CSS tags to manually tag individual items for tracking, if desired.

Example:

<script type="text/javascript">
var canalytics_custom = {};
canalytics_custom.advanced_disable = 1;
</script>

<!-- your hypothetical tracking code, which must go after canalytics_custom -->
<script src="http://stats.churchanalytics.com/js" type="text/javascript"></script>

canalytics_custom.pageview_disable

When our tracking code is loaded on your web site, it will automatically log each page view as it happens. You can disable functionality with this property, if desired. This is useful in scenarios where you only want data logged for certain events and actions.

Example:

<script type="text/javascript">
var canalytics_custom = {};
canalytics_custom.pageview_disable = 1;
</script>

<!-- your hypothetical tracking code, which must go after canalytics_custom -->
<script src="http://stats.churchanalytics.com/js" type="text/javascript"></script>

Manually tagging a link as a download, outbound link or click

The following file extensions are automatically tagged as downloads by our tracking code:

7z, aac, avi, csv, doc, exe, flv, gif, gz, jpg, jpeg, mp3, mp4, mpeg, mpg, mov, msi, pdf, phps, png, ppt, rar, sit, tar, torrent, txt, wma, wmv, xls, xml, zip

Likewise, links that start with the protocols listed below are automatically tagged as outbound links, supposing they don't point to the same domain that the code is currently running on:

http, https, mailto, ftp, telnet

You may wish to log downloads and outbounds on additional links that aren't supported by default by our code. Or, your site may have downloads and outbound links that link to an internal script first (typically to log the action in your own database) and then redirect the user to the actual file or link. These types of links do not get tagged automatically as downloads or outbounds, because they just look like internal links to the tracking code. There's no way for our code to know what will actually happen after the link is clicked.

Because of this, Church Analytics has a feature that lets you force the tracking code to tag a link as a download, outbound link, or click. Simply add one of the following classes to any link on your site, and our code will treat it as you have specified. The last class listed (canalytics_log) is for the 'click' type. Otherwise, use canalytics_log_download or canalytics_log_outbound if you want it to be marked like that.

<a class="canalytics_log_download" href="/download.php?file=sweet.mp3">Download!</a>
<a class="canalytics_log_outbound" href="/redirect.php?url=http://google.com">Google!</a>
<a class="canalytics_log" href="#ajax" onclick="MyAjaxFunction();">Click me!!</a>


These are logged similar to normal pages on your site with a URL and title. These are automatically extracted from the link by our tracking code. If there is no text for the link, we try to grab something meaningful instead. For example, if it is an image, we'll grab the URL of the image and use that for the title instead.

If you wish to customize the URL and/or title for these, you'll need to use our canalytics.log() javascript function.


You can also exclude specific links from being automatically counted as downloads or outbound links, if desired. You just need to add the class "canalytics_ignore" to the links you want ignored.

<a class="canalytics_ignore" href="http://sweetsite.com/cool.mp3">Sweet download</a>
<a class="existing_class canalytics_ignore" href="http://amazingsite.com">Amazing link</a>


Church Analytics's tracking code has functions you can use to log any action you want on your web site, and declare goals via Javascript events. We also offer a way to log data from internal scripts. This is not possible with other services, as they don't document how their incoming tracking API works, and they rely solely on the referrer to verify information. Church Analytics is different.

Tracking code functions

canalytics.log Log an action based on any Javascript event. URL, title, and action type can all be specified. canalytics.goal Log a goal as completed based any Javascript event.

canalytics.log( href, title, type )

Church Analytics works great for tracking events in Javascript and Flash applications. You'll simply need to call this function whenever you want to log a visitor action, with which you can specify a URL, title, and type:

  • href: Required. The URL you want logged for this action. Outbound links need to start with http, all other actions need to start with either a / or a #. If you just want to the log the URL as it is in the anchor tag, use the value this.href. (this.href will only work within the HTML scope, not in Flash).
  • title: Optional. The text you want to show up next to the URL. Our standard tracking code uses the text of the link itself but you may want to use something else.
  • type: Optional. The type of action you are logging. If left blank, it defaults to 'click'. Other options are 'download', 'outbound', and 'pageview'.

Javascript

You'll want to use an "onclick" event handler for the link to call the log function. For example:

<a href="#menu/home" onclick="menu('home'); canalytics.log('#menu/home','Home'); return false;"><img src="media/menu/home.gif"></a>

Flash (ActionScript)

Flash has built-in functions for calling external javascript functions.

For ActionScript 3 or higher, use this the code below, swapping out URL, TITLE, and TYPE for what you want to log. (URL is required, the others are optional).

ExternalInterface.call("canalytics.log", "URL", "TITLE", "TYPE");

For ActionScript versions less than 3, use getURL() instead. You'll need to prefix our function with the javascript: protocol. Replace URL, TITLE, and TYPE for what you want to log. (URL is required, the others are optional).

getURL("javascript:canalytics.log( 'URL', 'TITLE', 'TYPE' );");

canalytics.log() creates a 500 millisecond second pause whenever it is called, to ensure the user's browser has time to talk to us before moving on to the next page. You can change this value with canalytics_custom.timer. For Flash, we recommend setting this value to 0, since Flash apps don't generally load new HTML pages.

canalytics.goal( id, revenue )

This function lets you declare goals from any Javascript event, such as when the user clicks a button or downloads a file. An action will not be logged when calling this function. It just flags the visitor as having achieved the goal.

You can also track goals with canalytics_custom.goal, but it's important to note that these two methods are very different from each other. canalytics.goal() should only be called by a Javascript event. Any other usage may have unexpected results and is not supported.

canalytics.goal takes 2 parameters:

  • id: Required. Each goal has its own unique numeric ID in our database. The goal management page for any web site lists the ID for each goal next to the goal's name. You'll need to specify the ID for the goal you want tracked when you call this function.
  • revenue: Optional. If the result of this goal is always a fixed amount of revenue, you can easily specify that. However, if it's for a sale, and the value varies with each customer, your code will need access to the value of the revenue, either through Javascript, cookies, or internally. You will need to talk with your web developer(s) and/or your shopping cart provider to implement this functionality.


canalytics.goal doesn't have any kind of pause timer built into it. If the user is going to be redirected to a new page after this click, you need to add the pause manually to ensure the click is registered on our end. Conveniently, our tracking code has a built in function called canalytics.pause() that you can use to do this. It takes one parameter, which is the number of milliseconds you want to pause for. If you don't specify that, it will automatically use what you have declared with canalytics_custom.timer. If you have not declared that, then it will use the default value of 500 milliseconds (half a second).

Example:

<a onclick="canalytics.goal( '10', '9.95' );" href="mailto:me@me.com">Email me!</a>

<a onclick="canalytics.goal( '10' ); canalytics.pause( 500 );" href="/download.php">Download now!</a>

Logging data from an internal script

Church Analytics lets you log data from an internal script, such as PHP, ASP, Perl, etc. Other services don't offer this feature because they don't document their incoming "API", and they only verify incoming data from the referrer. Church Analytics is different.

This feature is useful in scenarios where data logging would not be possible with an external service such as Church Analytics. For example, many sites use internal redirects for outbound links. Because these internal redirects do nothing but "redirect", a full HTML page is never actually loaded on your web site, so our tracking code can't load and execute. But now, you can log data internally from that redirect script before sending the user on their merry way. This may introduce a slight delay in the redirect, but the benefit should outway the cost for most web sites.

Even better, you can also use this to update sessions at a later time. You can add custom data, goal completions, and goal revenue, even if the session is expired and happened 30 days ago. The goals in particular should be useful for those of you who are unable to embed our tracking code, or custom Javascript variables, in your shopping cart pages. You can find the session ID on Church Analytics at a later time, and then update it using this code. (We plan to add a way to do this directly from your stats as well in the near future).

If you have used the stats API at all, you should be familiar with the Site Key. This is like a password to access your data. The site key is for reading data only, however. For writing data, we have created the admin site key. Anyone with access to your admin site key will be able to log data to your stats, so you should not share it with anyone. Both site keys are available from the main preferences page for any site.

How to talk to our tracking servers

The page you want to talk to is at http://stats.churchanalytics.com/in.php. This is the same script that our tracking code talks to. You just need to send the right parameters, and we'll log it.

How do you send data to this script, from your script? All web languages have functions that can talk to external scripts on remote servers. In PHP, one such function is file. There are other functions available, the main difference being how the data from the remote script is returned to you, but that doesn't matter for this usage. in.php will not return anything to you.

Most default installations of PHP allow these functions to talk to remote servers like ours, but an administrator does have the ability to turn this feature off. Make sure to ask your administrator or web host if this feature is enabled, otherwise you will have to use another method such as cURL, which is not documented on this page.

Required parameters

These parameters are required with all requests. They are all available from the main preferences page for any site on Church Analytics. Additional parameters are necessary depending on what you are trying to do. Each type of call is documented further down.

  • site_id

    Every site on Church Analytics has its own unique ID. This is that.

  • sitekey_admin

    There's the sitekey, and then there's the admin sitekey. This one allows you to write data to Church Analytics. Do not share this key with anyone else.

  • ip_address / session_id

    You must include one of these, so we know who this data is for. Generally, you're going to specify the IP to log actions "live" as they are happening (since you won't know the session ID at the time), and you'll want to use the session ID when you are updating a session at a later time to add a goal or custom data to it. You can get the visitor's IP address in PHP with $_SERVER['REMOTE_ADDR']. If you forget to include both of these, Church Analytics will use the IP of the connecting machine instead, which in this case would be your server's IP - not what you want!

IMPORTANT! Always URL encode all parameters that you send. Otherwise, there is a very good chance the request will fail.

Logging an action

To log an action, you can use the following parameters. href is required, all others are optional.

  • href

    The URL of the action. Outbound links should start with "http". All others should start with a slash / or a hash #. /this/is/ok
    #thisIsOk
    this/is/NOT/ok
  • title

    The title of the action. For a page view, this would be the document title. Note that each unique URL logged to your site can only have one page title ever associated with it.
  • type

    Options are pageview, download, outbound, and click. If left blank, or an invalid value is declared, pageview will be used.
  • ref

    The external referrer, if any, for this action (e.g. if they arrived at your site from a link or search on another site). This value will only be logged for the very first action of a session.
  • ua

    The visitor's user agent, e.g. Mozilla/5.0 (Windows; U; Windows NT 5.1; en-GB; rv:1.9.0.6) Gecko/2009011913 Firefox/3.0.6.
  • Our code will automatically extract the browser and OS information from it so you should pass it through "as is".

Example:

// URL encode your values!
$href = urlencode("/some/page");
$title = urlencode("Some title");
$ref = urlencode( $_SERVER['HTTP_REFERER'] );
$ua = urlencode( $_SERVER['HTTP_USER_AGENT'] );

file("http://stats.churchanalytics.com/in.php?site_id=1&sitekey_admin=1&ip_address=".$_SERVE['REMOTE_ADDR']."&href=".$href."&title=".$title."&ref=".$ref."&ua=".$ua);



Logging custom data

You can log custom data to any existing session, even one many days old, without generating a visitor action.

  • type

    Required, and its value must be "custom".
  • custom

    Required, of course - the point of this request is to log custom data! This should be an array of key/value pairs you want to send. How do you send an array in the URL? See the example below!
Example: // URL encode your values!
$username = urlencode( $_SESSION['username'] );
$email = urlencode( $_SESSION['email'] );

file("http://stats.churchanalytics.com/in.php?site_id=1&sitekey_admin=1&session_id=123&type=custom&custom[username]=".$username."&custom[email]=".$email);



Logging a goal and/or revenue

You can declare a goal for a session well after it has expired, without generating a visitor action. You can also attach revenue to that goal. You can even attach revenue to a goal that has already been flagged as completed for this session, if revenue was not logged previously.

  • type

    Required, and its value must be "goal".
  • goal

    Required, of course - the point of this request is to log a goal! This should be an array, with keys "id" (required) and "revenue" (optional). How do you send an array in a URL? See the example below!
Example:

file("http://stats.churchanalytics.com/in.php?site_id=1&sitekey_admin=1&session_id=123&type=goal&goal[id]=123&goal[revenue]=49.95");



Jump Back to the Top!
Sign In

Need to register? Click here