harvest object

Note

When running the examples codes below, make sure you have turned on console debugging.

The Harvest object contains of several helpers.

trackEvent

This function is used to track user interaction. More information can be found in the Javascript API documentation.

Helper functions

getUserID

The getUserID function can be used to easily retrieve the userID of the visitor. When there is no userID available, for example because no event has been tracked yet, the userID will be created.

var userID = harvest.getUserID();

setCookieConsent

This functions will set the consent of the user. It will use the name of the cookie as defined in the Harvest Console.

This function accepts one parameter with the following properties:

Property	Required	Description
ID	No	If no ID is provided, a uuid is generated
templateID	No	The template ID can be used for own reference to specific consent versions.
createdAt	No	The timestamp of creation of the consent, it not provided, this will be generated.
permissions	Yes	Object of given permissions. Properties are the names of the permissions and the value is a boolean.

Example for an account that has the following permissions:

Permission name	Default value	Is optional?
functional	true	No
advertising	false	Yes

If a user accepts all permissions, a call to this function would look like this.

harvest.setCookieConsent({
    "permissions": {
        "functional": true,
        "advertising": true
    }
});

We leave the ID and createdAt out, so they will be generated automatically. In this case we do not use a templateID.

If a wrong permission is sent, the permission will be discarded. If a permission is missing, the default value is used.

For more information about consent, read our cookie consent documentation.

getCookieConsentData

This function is the getter that is related to setCookieConsent. The function retrieves the cookie consent object. It can be really useful if you want to know whether a user has given a certain permission.

For more information about consent, read our cookie consent documentation.

var consentData = harvest.getCookieConsentData();
console.log(consentData.permissions); //This logs the permissions and whether a user has given it or not.

createUniqueID

hashSha256

For more information about hashing, read our hashing documentation.

Cookie control

createCookie

This helper functions lets you create a cookie. You need to supply the name, value and amount of days before it should expire.

readCookie

This helper function allows you to read a cookie. You will need to supply the name of the cookie. If the cookie does not exist, you will get null.

removeCookie

This helper function allows you to delete a cookie. You will need to supply the name of the cookie.

upsertCookieData

This helper function allows you to easily add a property to a JSON cookie. You will have to supply the name of the cookie, the property you want to upsert and the value. You also need to supply the amount of days before the cookie should expire. If no cookie exists or if the JSON is malformed, an empty object will be used to add the property to.

getJSONCookie

This method allows you to easily retrieve a JSON cookie. If no cookie exists or if the JSON is malformed, an empty object will be returned.

getJSONCookieValue

This method allows you to easily retrieve the value of a property of a JSON cookie. If no cookie exists or if the JSON is malformed, an empty object will be returned.

setUserMeta

This methosd allows you to persists meta data about the user. This methods requires 2 parameters: 1. The name of the variable and 2. The value of the variable. The data will be saved in the harvest_user_meta cookie. This cookie has the same expiration as the harvest_user cookie. You can use the harvest.getJSONCookieValue to obtain the information. This information will also automatically be added to the event.

setSessionMeta

This methosd allows you to persists meta data about the user. This methods requires 2 parameters: 1. The name of the variable and 2. The value of the variable. The data will be saved in the harvest_session_meta cookie. This cookie has the same expiration as the harvest_session cookie. You can use the harvest.getJSONCookieValue to obtain the information. This information will also automatically be added to the event.

//First we set an object to local storage
var data = {
        "firstName": "Jos"
};

//Save the data to a cookie
harvest.createCookie("demoData", JSON.stringify(data), 4);

//Read the data from a cookie
console.log("First read", harvest.readCookie("demoData"));

//Upsert the cookie data
harvest.upsertCookieData("demoData","lastName", "IJntema", 4);

//Read the data from a cookie
console.log("Second read", harvest.readCookie("demoData"));

//Read the JSON cookie
console.log("JSON cookie read", harvest.getJSONCookie("demoData"));

//Read the value from the JSON cookie
console.log("JSON cookie value read", harvest.getJSONCookieValue("demoData", "lastName"));

//Delete the cookie
harvest.removeCookie("demoData");

//Read the data from a cookie
console.log("Third read", harvest.readCookie("demoData"));

Local storage control

removeLocalStorageItem

This is a helper function to remove an item in local storage.

setLocalStorageItem

This is a helper function to set an item in local storage.

getJSONLocalStorage

This is a helper function that retrieves a JSON value from local storage. If the cookie does not exists or the JSON is malformed, it returns an empty object.

//First we set an object to local storage
var data = {
        "firstName": "Jos"
};

//Save the data to local storage
harvest.setLocalStorageItem("demoData", JSON.stringify(data));

//Read the data from local storage
console.log("First read", harvest.getJSONLocalStorage("demoData"));

//Delete the data from local storage
harvest.removeLocalStorageItem("demoData");

//Read the data from local storage
console.log("Second read", harvest.getJSONLocalStorage("demoData"));

Experiment data

AB-testing and personalization is important to improve your website. We have several helper function to make it easier to track experiments. Besides having multiple integrations with AB-testing tools, we also offer the possibility to use Harvest for custom testing.

setExperimentData

This function requires two parameters: experimentID and variantID. It will set a cookie with the same expiration as the use cookie.

The cookie is read when an event is triggered and will at the experiment meta data to the event.

Debugging

setMockReferrer

In principle Harvest takes the document.referrer variable to determine the referrer. This is correct behavior in production, but it is sometimes not ideal when debugging.

You might want to test some scenario’s which require you to have a different referrer. This is where you can use harvest.setMockReferrer for. You can provide a referrer url and Harvest determines the referrer not based on document.referrer, but it takes the referrer you filled in.

You can use the example below. If you run this code and check the final event of the pageview, you will see that the referrer is now “https://www.yourreferrer.com”.

harvest.setMockReferrer("https://www.yourreferrer.com");

harvest.trackEvent({
    "event": "pageview",
    "data": {}
});

setMockURL

Usually you want Harvest to use the current location information to determine the page you are on. This might not always be what you want when debugging. Instead of checking every page manually, you can also programmatically change the “current url”.

In the example below you will have to replace <Your url> with your base url. Then run the code and check the pageData of the final event. You will see that Harvest took the url you set as the current url.

harvest.setMockURL("<Your url>/test?utm_source=test&utm_medium=test");

harvest.trackEvent({
    "event": "pageview",
    "data": {}
});

startMinimalDebug

harvest.startMinimalDebug is used to set basic debugging , read our debugging documentation for more information.

When using this function, you will create the harvest_collect_debug cookie.

harvest.startMinimalDebug();

startExtensiveDebug

This method also enables debugging, but the extensive logging variant.

stopDebug

With this function you can stop debugging.

When using this function, you will delete the harvest_collect_debug cookie.

harvest.stopDebugging();

timer

This function let’s you retrieve timings. These timings are useful to check how long certain actions took.

For more information, read the timing documentation.

Persisting meta data

In principle, all data that is used during an event is pushed with the event. This can either be done through our Javascript API or data attributes.

It can however be useful to have some data that is persisted through multiple events.

Page meta data

The harvest.pageMetaData object contains information that is tracked with pageviews. Whenever a pageview is tracked, Harvest extracts the data-object that was sent with it. This object will be saved in the harvest.pageMetaData object. All non-pageview events will then be enriched with the data-object.

This way we can enrich all events with meta information about the page.

When using data-track-page, before any data attribute is tracked, Harvest collects the data object from the data-track-page object, to make sure that all tracked events will contain the meta data of the page.

As an example you could run the code below. First of all, after the pageview, the pageMetaData will be logged to the console and you will see it contains the provided “pageLanguage”. After that, you can check the final event of the demo productDetailView. You will see that “pageLanguage” is filled in pageData.

harvest.trackEvent({
    "event": "pageview",
    "data": {
         "pageLanguage" : "NL"
    }
});

console.log("This is now your pageMetaData", harvest.pageMetaData);

harvest.trackEvent({
    "event" : "contentview",
    "data" : {
        "viewType": "productDetailView",
        "products": [{
            "name": "Demo"
        }]
    }
});

Global meta data

Page meta data will be refreshed everytime a pageview is tracked. This is in contrast to global meta data. Anytime you can set the harvest.globalMetaData and from then on, the data in globalMetaData will be added to all subsequent events.

You could for example run the code below. You will see that the variable “globalVariable” will be in the eventData of the final event.

harvest.globalMetaData = {
    "globalVariable": "Variable value"
};

harvest.trackEvent({
    "event": "pageview",
    "data": {}
});