Installing Firstparty.js
In general, you should follow the installation instructions shown when you create your Javascript Source in Firstparty.
The Firstparty.js snippet loads the Firstparty.js library and configures the library to send collected Events to the Source you've specified via the domain you've configured in Firstparty.
Measurement Methods
Firstparty.js relies on two simple methods to collect Events: page and track.
Track
The track method collects Events as generated by visitors to your website. You may name your as you see fit, but we recommend a pattern of two words, starting with a noun and ending with a past-tense verb. For example, you may have Events such as "Page Viewed", "Form Completed", or "Button Clicked". You may read more about best-practices when naming events on the Events documentation page.
Firstparty is different from most other measurement platforms in that the only method that collects data is track. Additional covenience methods may exist in specific Source SDKs (such as the page method below), but underneath, every measurement request is a track request.
The track method signature accepts four arguments: the Event name, an optional object of Event Properties, an optional object of options to contextualize collecting the Event, and an optional callback function run after the Event is collected.
firstparty.track(event, [properties], [options], [callback]);
The track method has the following fields:
| Argument | Required | Description |
|---|---|---|
event | required | The required name of the Event to collect |
properties | optional | An optional key-value object of properties to collect along with the Event. If the Event name was "Form Completed", one property may be "email_address" |
options | optional | An optional, currently unused object reserved for future optional settings when collecting an Event |
callback | optional | An optional javascript function that will execute after a short amount of time, to allow the Event to be sent to Firstparty |
An example track call might look like this:
firstparty.track('Form Completed', {
form: 'Contact Us',
first_name: 'Johnny',
last_name: 'Rose',
email: 'johnny@rosebudmotels.com',
});
Page
The page method is an extension of Track that automatically sets the Event name to "Page Viewed" and collects the Event. It is meant to make it easy to collect page views on a website, and collects additional contextual data about the page at the time of collection.
A page call is added by default in the Firstparty.js snippet provided in your Javascript Source setup screen. You may modify that page call, or even remove it completely.
The page method signature accepts five optional arguments: the category of the page, the name of the page, an object of Page Properties, an object of options to contextualize collecting the Page information, and an optional callback function run after the page data is collected.
firstparty.page([category], [name], [properties], [options], [callback]);
The page method accepts the following arguments:
| Argument | Required | Description |
|---|---|---|
category | optional | An optional category of the page. NOTE: If the page method only receives one argument, it is assumed that argument is the name. You must include both a name and category (in that order) to send a category. |
name | optional | A specific name of the page. If nothing is passed, the value of the <title> tag will be used to determine the name. |
properties | optional | An optional key-value object of properties to collect along with the Event. |
options | optional | An optional, currently unused object reserved for future optional settings when collecting an Event. |
callback | optional | An optional javascript function that will execute after a short amount of time, to allow the Event to be sent to Firstparty. |
An example page call might look like this:
firstparty.page();
A page call will automatically set several Properties for you based on data from the vistor's browser, unless specifically overridden:
firstparty.page('Contact', {
title: 'Contact Us',
url: 'https://rosebudmotels.com/contact',
path: '/contact',
referrer: 'https://google.com/'
});
Firstparty.js is based on the incredible open-source Analytics.js from our friends at Segment.