Overview

Visit our website at http://www.journity.com

This documentation is divided into three sections:

Profile

Below is an example profile and a description of each section.

{
  "extra" : {
    "downloads" : [
      "file.pdf"
    ]
  },
  "total_visits" : 9,
  "orders" : {
    "1000" : {
      "name" : "",
      "total" : 15,
      "state" : "",
      "items" : {
        "TEST" : {
          "unit_price" : 1,
          "name" : "Test item",
          "qty" : 15,
          "category" : ""
        }
      },
      "city" : "",
      "tax" : 0,
      "shipping" : 0,
      "country" : ""
    }
  },
  "original_referrer" : "google.com",
  "referrers" : {
    "" : 20,
    "google.com" : 7
  },
  "session" : {
    "continent" : "North America",
    "postal" : "20500",
    "lat" : "38.8977",
    "city" : "Washington",
    "long" : "-77.0366",
    "ip_address" : "4.2.2.2",
    "region" : "District of Columbia",
    "country" : "United States"
  },
  "session_engagement" : {
    "1" : {
      "first_seen" : "2016-02-08T19:43:17.000Z",
      "score" : 1,
      "total_read_seconds" : 65,
      "total_seconds" : 65,
      "last_seen" : "2016-02-08T20:14:41.000Z",
      "scan_total" : 0,
      "blink_total" : 1,
      "read_total" : 1
    },
    "3" : {
      "score" : 1.5,
      "first_seen" : "2016-03-04T20:20:34.000Z",
      "total_read_seconds" : 210,
      "total_seconds" : 210,
      "last_seen" : "2016-03-04T20:36:38.000Z",
      "scan_total" : 3,
      "blink_total" : 4,
      "read_total" : 3
    },
    ... // Removed for brevity
  },
  "groups" : {
    "user" : {
      "expires" : null,
      "added" : "2016-03-21T22:45:31.118Z"
    },
    "admin" : {
      "expires" : null,
      "added" : "2016-03-21T22:30:32.676Z"
    },
  },
  "site_sections" : {
    "faith" : {
      "scan_total" : 0,
      "read_total" : 0,
      "blink_total" : 3,
      "score" : 0,
      "first_seen" : "2016-03-04T20:26:21.000Z",
      "total_read_seconds" : 0,
      "name" : "faith",
      "last_seen" : "2016-03-04T20:27:49.000Z",
      "total_seconds" : 20
    },
    "radio" : {
      "total_seconds" : 20,
      "last_seen" : "2016-03-04T20:26:18.000Z",
      "name" : "radio",
      "total_read_seconds" : 0,
      "score" : 1,
      "first_seen" : "2016-03-04T20:25:23.000Z",
      "read_total" : 0,
      "blink_total" : 0,
      "scan_total" : 1
    },
  },
  "content_categories" : {
      "faith" : {
         "total_read_seconds" : 0,
         "total_seconds" : 0,
         "scan_total" : 0,
         "last_seen" : "2016-03-24T16:55:59.000Z",
         "score" : 0,
         "first_seen" : "2016-03-24T16:55:59.000Z",
         "blink_total" : 1,
         "read_total" : 0
      },
      "theology" : {
         "total_read_seconds" : 0,
         "total_seconds" : 10,
         "scan_total" : 0,
         "last_seen" : "2016-03-24T16:55:59.000Z",
         "score" : 0,
         "first_seen" : "2016-03-24T16:55:43.000Z",
         "read_total" : 0,
         "blink_total" : 2
      }
  },
  "donations" : {
    "15" : {
      "total" : 5,
      "categories" : null,
      "last_donation" : "2016-03-22T01:09:27.139Z",
      "cause" : "General"
    },
    "30" : {
      "total" : 5,
      "categories" : null,
      "last_donation" : "2016-03-22T01:10:16.383Z",
      "cause" : "General"
    }
  },
  "score" : 63,
  "identity" : {
    "phonenumbers" : null,
    "title" : "",
    "addresses" : null,
    "socialnetworks" : null,
    "fname" : "",
    "birthday" : null,
    "mname" : "",
    "emailaddresses" : null,
    "lname" : ""
  },
  "recent_content" : [
    {
      "length" : 135,
      "timestamp" : "2016-03-22T01:30:55.000Z",
      "url" : "http://website.fake/faith",
      "title" : "Fake Website"
    },
    {
      "title" : "Fake Website - Faith",
      "length" : 80,
      "timestamp" : "2016-03-16T00:55:31.000Z",
      "url" : "http://website.fake/"
    },
    ...
  ],
  "lifetime" : {
    "scan_total" : 6,
    "read_total" : 15,
    "blink_total" : 8,
    "score" : 2.625,
    "first_seen" : "2016-02-08T19:43:17.000Z",
    "total_seconds" : 1045,
    "last_seen" : "2016-03-22T01:30:55.000Z",
    "total_read_seconds" : 1045
  },
  "topSections" : [
    "resources",
    "faith"
  ]
}

Section definitions

extra: The extra section is essentially a key/value store on the profile that can store arbitrary data to be used in campaign filtering.
total_visits: The total number of site visits.
orders: The list of completed orders for the user. Includes items if that information was captured. See Orders original_referrer: The original referring site that initially brought the user to your site.
referrers: The list of all referrers and their score for number of visits.
session: Information ont he current session, primarily geolocation based.
session_engagement: The list of visits and their aggregate scores and times.
groups: The list of user groups and their expiration dates. See Groups
site_sections: The site sections that the user has visited and their aggregate scores and times.
content_categories: The categories that the user has visited and their aggregate scores and times.
donations: The list of donations that have been added for the user. See Donations
score: The profile score. This is the general user's engagement score.
identity: Any identifying information such as email. This is not yet implemented and could change for security reasons.
recent_content: The most recent urls visited.
lifetime: Lifetime aggregate values. Note that the score here is not the same as the engagement score.
topSections: The user's most visited sections in order. This is often used for content affinity.

Collector

The collector scores your users on their engagment with the site, sections, and topics. Its expanded API allows you to store custom information in their profile, including store transactions, donations, user groups, and any additional information for the user. The information can then be later filtered in personalizer call-to-actions.

All collector calls are made on a global _jt_ object or the window._jt_ alias.

Below are the functions available.

Events

pageview

The pageview call registers a pageview. This is normally done inside of the collector but is added for any dynamic page changes that are not tracked correctly. It takes only optional arguments, and uses the URL from the address bar.

Arguments:

Example:

_jt_("pageview"); // Typical use case

// Advance usage
_jt_("pageview", {
  subsite: '123', // Unique name or id associated with data
  sections: {   // Extra segmentation data
    "Product": "Pride and Prejudice",
    "Type": "Book",
    "Author": "Jane Austen"
  }
});

Groups

add-group

The add-group call appends a group to the user's groups.

Arguments:

Examples:

_jt_("add-group", "donors");

Extra Data

add-extra

The add-extra call allows you to store any JSON serializable data into the profile by key. If the key already exists it will be overwritten.

Arguments:

Examples:

//Adds the downloaded-book key and sets it to true.
_jt_("add-extra", "downloaded-book", true);

// The below adds a download to an array.
// Note that this isn't completely atomic so could cause a race condition if "downloads"
// already exists in the extra data and the user is somehow browsing multiple sessions.

// Assumes that the personalizer is accessible as the global variable "p"
p.run(); // First updates the profile from the server to minimize race conditions
var extra = p.profile.get("extra");

// If there are no extra fields, extra will be undefined.
// Similarly, if we've not added a first download, it'll be undefined.
var downloads = (extra && extra['downloads']) || [];
downloads.append("file.pdf");
_jt_("add-extra", downloads);

Donations

add-donation

add-donation adds a donation to the profile.

Arguments:

Example:

_jt_("add-donation", "73", {"total": "20.00"})

Orders

add-trans

add-trans starts a new transaction for a store order. It is coupled with finish-trans when the order is complete and any number of items added by add-item. It takes a single argument, opts, which is a javascript object with the following structure:

Example

var order = {"id": 1000, "total": 10.50, "tax": 0.00};
_jt_("start-trans", order);

add-item

The add-item call follows an add-trans call and allows adding items to a store order. It is called with single argument, opt, with the following structure:

finish-trans

finish-trans completes an order and commits it to the profile. It takes no arguments, and closes the most recently opened order.

Personalizer

The personalizer by default is not in the global namespace, but can be configured to be accessible. It is instantiated as part of the personalization bundle (and so can be updated via s3 rather than a script change on the page). The code below assumes that the personalizer is globally named p.

Profile

The following shows how to retrieve and view the profile.

run

The run function updates the profile from the remote server. It does not re-load campaigns or call-to-actions.

Example:

p.run();

profile

The profile object (of type ProfileWrapper) is the profile from the server and is available in campaign filters (to later be accessible on the dashboard).

Example:

p.profile.get("groups"); //Get the groups associated with the profile
var data = p.profile.raw(); //Gets the raw profile object

Callbacks

addCallback

The addCallback function adds a function to be called when the profile is loaded initially from the server. The function takes a single argument, the profile wrapper described above. To alter the profile, see addProfileProcessor below.

addProfileProcessor

The addProfileProcessor function adds a function to be called when the profile is loaded the allows aggregation for a profile. It is called with a single argument, the profile wrapper described above. It should return the profile.

Example:

//Counts the number of downloads in the "extra" data
var callback = function(profile) {
    var extra = profile.extra;
    var count = 0;
    if (extra) {
      var downloads = extra.downloads || [];
      count = downloads.length;
    }
    profile['downloadCount'] = count;
    return profile;
};

p.addProfileProcessor(callback);
p.run();

addCTALoadCallback

addCTALoadCallback adds a callback to be called when a call-to-action is loaded (appears on the page). It is typically used for analytics. Note that this is not necessarily at page load; it could be invoked at a certain scroll percentage or at other times. The callback will receive 4 arguments when called:

addCTAActionCallback

addCTAActionCallback adds a callback to be called when a call-to-action's button is clicked. It is typically used for analytics. The callback will receive 4 arguments when called:

addCTADismissCallback

addCTADismissCallback adds a callback to be called when a call-to-action's close or dismiss button is clicked. It is typically used for analytics. The callback will receive 4 arguments when called: