Capturing event data

Introduction

Prepr is powered by graph database technology, meaning you can capture events, and store and process big data. With this, we enable you to segment and personalize content for your customers.

You can track actions your customers take as events, both while logged into your site and while visiting your website. Once you start tracking events in Prepr, you can segment your customers and start personalizing your site.

Every event is associated with an event type, the time it happened, the customer that caused the event, and optionally some metadata. Events can be created using the Prepr Pixel or the REST API.

Event types

Event types are specifying the kind of event the customer has with your content. For example when a customer views an article a View event is recorded.

Constraint events can only be created once in a Customer-Content relationship.

TypeConstraint
ViewOptional
Expose (A-B Testing with Optimize)Optional
LikeYes
UnlikeN/A
CommentOptional
BookmarkYes
UnbookmarkN/A
SubscribeYes
UnsubscribeN/A
PurchaseOptional
VoteOptional
UnvoteN/A
ClickthroughOptional
ShareOptional
SignUpOptional

'Un*' events like 'Unlike', 'Unbookmark' and 'Unsubscribe' will delete the User-Content relationship. They don't have any effect on your engagament.

Pixel

First time set up

To start collecting basic event data from a website you can use the Prepr Pixel to record an event stream.

<!-- Start Prepr Open Pixel -->
<script>
  !function (e, t, n, p, o, a, i, s, c) {
  e[o] || ((i = e[o] = function () {
    i.process ? i.process.apply(i, arguments) : i.queue.push(arguments)
  }).queue = [], i.t = 1 * new Date, (s = t.createElement(n)).async = 1, s.src = "https://cdn.tracking.prepr.io/js/openpixel.min.js?t=" + 864e5 * Math.ceil(new Date / 864e5), (c = t.getElementsByTagName(n)[0]).parentNode.insertBefore(s, c))
}(window, document, "script", 0, "opix"),
  opix("init", "{{ACCESS_TOKEN}}");
</script>
<!-- End Prepr Open Pixel -->

Sign in to your Prepr account
Go to https://signin.prepr.io and sign in with your Prepr account credentials. Then navigate to the Environment you want to record events for.

Create an Access token
Go to Settings -> Access tokens and click Add access token.

Enter Tracking Pixel {{URL}} as name and replace {{url}} by the domain (e.g., example.com, not www.example.com/) you are going to use the tracking pixel on.

Click save and copy the generated access token, you need this later.

Add the code snippet to your website
You find the Prepr Tracking Code above. Copy and paste this code as the first item into every web page that you want to track. Replace {{ACCESS_TOKEN}} with the access token created above.

Send events

You will need to have the Prepr Pixel set up first to send events. Once added, you can submit an event using the event method. This will associate the event with a currently logged-in customer or logged-out visitor. Optional metadata can be sent with the event.

In the example below we send a View event for a published blog post:

opix('event', 'View', {
    'publication':'85260a17-2998-47ea-908e-3b988e18a494'
});

To associate a event with a existing (prepr) user, a optional parameter can be added. If the person's ID is not found in your customers list when the event gets processed, a new customer will be created.

opix('event', 'View', {
    'publication':'85260a17-2998-47ea-908e-3b988e18a494',
    'person':'fb485350-c0e4-45cf-aaf4-faf837759203'
});

Add a event value

A event value can be added to give weight to some events. For example in e-commerce Purchase events can contain the value of the product purchased. By default events receive a 1 value.

opix('event', 'Purchase', {
    'publication':'85260a17-2998-47ea-908e-3b988e18a494',
    'person':'fb485350-c0e4-45cf-aaf4-faf837759203',
    'value': 32.50
});

Capturing AB-test events

If you are using Prepr AB-tests you need to record Expose and View events to measure the succes of a experiment. Expose events are not visible in the customer profile, but are recorded behind the scenes for A/B testing evaluation only.

Add the same customer ID you are using in the AB-test requests as the ab_testing param.

opix('event', 'Expose', {
    'publication':'85260a17-2998-47ea-908e-3b988e18a494',
    'ab_testing':'fb485350-c0e4-45cf-aaf4-faf837759203',
    'locale':'en-GB' // Only applies on multi language publications
});

If you're creating multi language publications. Don't forget to pass the locale param in every event.

Add custom metadata

All events have a metadata (data) field that allows you to set custom-defined key/value data about an event.

opix('event', 'View', {
    'publication':'85260a17-2998-47ea-908e-3b988e18a494',
    'data':{
        'referral':'example.com',
        'invited_by':'c532586c-1e9c-4f26-b8ba-113178c58133'
    }
});

Event constraints

Prepr can help to enforce data integrity with the use of constraints. Constraints can be applied to supported event and will guarantee both existence and uniqueness. A event that violates the constraint will be discarded.

Check out the Event types to see if your event supports constraints.

Subscribe, Like and Bookmark events have a constraint by default.

opix('event', 'View', {
    'publication':'85260a17-2998-47ea-908e-3b988e18a494',
    'constraint': true
});

REST

With the REST API you can send event data to Prepr. This may be convenient for offline conversions or if you're working in a restricted environment and aren't allowed to load third-party Javascript snippets.

Fields

The table below shows the fields that are supported in the REST API.

argumenttyperequireddescription
labelStringYesDefines the event type.
valueFloatEngagement value (default 1).
timestampUTC Timest.Event timestamp (default time of request).
constraintBooleanEnforce constraint.
Publication Data
publicationArrayYes
publication.idStringYesPublication ID the event is recorded for.
publication.localeStringLocale like en-GB.
Customer Data
personArrayYes
person.idStringID of Prepr User
person.reference_idStringCustom unique visitor ID.
person.ab_testingStringUser ID for AB-testing.
ip_addressStringIP Address used to look-up locations.
Custom Data
dataArrayAdd custom event data.

You need to supply a person.id or a person.reference_id for the event to be recorded.

If a unknown person.reference_id is found a new customer will be created.

Send events

If you collected all the data, the JSON data object should be posted to the following endpoint:

POST https://tracking.prepr.io/events

{
    "label" : "View",
    "timestamp" : 1609588800, // Optional
    "publication" : {
        "id" : "76a5e261-ec2a-4bd2-8195-cf7e889b0a68"
    },
    "person" : {
        "reference_id" : "x-21381723243-PRP"
    }
}

This endpoint requires a HTTP Authorization header with a Access Token containing the capture_publish scope.

If the event was successful queued the endpoint will return a status code 202 Accepted.

The endpoint won't validate all the input. Processing of the events are queued.

To validate your input, within a few minutes, you'll see the data reflected in the Prepr Engagement page.

Event constraints

Prepr can help to enforce data integrity with the use of constraints. Constraints can be applied to supported event and will guarantee both existence and uniqueness. A event that violates the constraint will be discarded.

Check out the Event types to see if your event supports constraints.

Subscribe, Like and Bookmark events have a constraint by default.

Add custom metadata

All events have a metadata (data) field that allows you to set custom-defined key/value data about an event. An example is showen below:

{
    "label" : "View",
    "value" : 1,
    "timestamp" : 1609588800,
    "data" : {
        "ref_url" : "/news/liveblog"
    },
    "publication" : {
        "id" : "76a5e261-ec2a-4bd2-8195-cf7e889b0a68"
    }
}