The purpose of this document is to describe the way clients can connect and push their data to the SmartOcto system. This data will later be visible on SmartOcto applications and used by ML algorithms.
SPECIFICATIONS
This document describes the following data types:
- Page views
- Application views
- Active users statistics
- Video page views
- Video application views
- Posts
- Conversions
- ReadingTime
- TwitterTweets
- TwitterMetrics
- Homepage
- Segment
- Segment Events
- Newsletter
- Push notification
Page views
|
Parameter |
Description |
Mandatory/Optional |
|
eventType |
Indicates type of event, pageViews |
Mandatory |
|
propertyId |
Your internal reference of the data group |
Optional |
|
uri |
URL of the viewed page |
Mandatory |
|
relationId |
Unique identifier for post, or path of the uri compiled by client |
Optional |
|
views |
Amount of collected views for post |
Mandatory |
|
timestamp |
Date time for collected views |
Mandatory |
|
referrer |
Referrer full path from which content is consumed |
Optional |
|
platform |
Which platform is used to consume the content |
Optional |
|
campaign |
Utm campaign |
Optional |
|
medium |
medium or Utm medium |
Optional |
|
source |
source or Utm source |
Optional |
Important
The values in the fields medium and source are used to determine and visualize the channels in the application of smartocto. In case no values for medium and/or source is added to a pageview, the default values of none (for medium) and direct (for source) are used.
Example without medium and source:
The pageview will be seen as direct traffic
{
"eventType": "pageViews",
"propertyId": "property_id",
"uri": "https://yourdomain.com/post/url/with/post-id/abc123def567/?some=parameter&is=filled",
"relationId": "abc123def567",
"views": 14,
"timestamp": "2022-05-19T23:59:59+01:00",
"referrer": "instagram.com",
"platform": "web"
}
Example with medium and source
{
"eventType": "pageViews",
"propertyId": "property_id",
"uri": "https://yourdomain.com/post/url/with/post-id/abc123def567/?some=parameter&is=filled",
"relationId": "abc123def567",
"views": 140,
"timestamp": "2022-05-19T23:59:59+01:00",
"referrer": "https://referrerdomain.com/example-path/",
"platform": "web",
"campaign": "utm_campaign_value",
"source": "social",
"medium": "facebook"
}
Example with utm_medium and utm_source used from campaign-tags
{
"eventType": "pageViews",
"propertyId": "property_id",
"uri": "https://yourdomain.com/post/url/with/post-id/abc123def567/?some=parameter&is=filled",
"relationId": "abc123def567",
"views": 140,
"timestamp": "2022-05-19T23:59:59+01:00",
"referrer": "https://referrerdomain.com/example-path/",
"platform": "web",
"campaign": "weekend_newsletter",
"source": "newsletters",
"medium": "mail"
}
Application views
|
Parameter |
Description |
Mandatory/Optional |
|
eventType |
Indicates type of event, appViews |
Mandatory |
|
propertyId |
Your internal reference of the data group |
Optional |
|
uri |
URL of the viewed application screen |
Mandatory |
|
relationId |
Unique identifier for post, or path of the uri compiled by client |
Optional |
|
views |
Amount of collected views for post |
Mandatory |
|
timestamp |
Date time for collected views UTC (ISO 8601) |
Mandatory |
|
platform |
Which platform is used to consume the content |
Optional |
Example
{
"eventType": "appViews",
"propertyId": "property_id",
"uri": "screen name / with / post-id / abc123def567",
"relationId": "abc123def567",
"views": 140,
"timestamp": "2022-05-19T23:59:59+01:00",
"platform": "app"
}
Active users
|
Parameter |
Description |
Mandatory/Optional |
|
eventType |
Indicates type of event, activeUsers |
Mandatory |
|
propertyId |
Your internal reference of the data group |
Optional |
|
device |
Device type for which number of active users is recorded |
Mandatory |
|
users |
Amount of collected users for brand in period |
Mandatory |
|
timestamp |
Date time for collected users for the last 30 minutes. This can be different for raw data type and aggregated type. UTC (ISO 8601) |
Mandatory |
|
platform |
Which platform is used to consume the content |
Optional |
Example of aggregated active users
{
"eventType": "activeUsers",
"users": 23,
"timestamp": "2022-05-19T23:59:59+01:00",
"device": "tablet",
"propertyId": "property_id",
"platform": "web"
}
Posts (used for stories AND videos)
|
Parameter |
Description |
Mandatory/Optional |
|
eventType |
Indicates type of event, post |
Mandatory |
|
title |
Title of the post |
Mandatory |
|
relationId |
Unique identifier for post |
Optional |
|
uri |
Post url |
Mandatory |
|
author |
Author of the post |
Mandatory |
|
section |
Section for the post |
Mandatory |
|
sectionPath |
Path for nested section, seperated by '/' |
Optional |
|
timestamp |
Publication date and time of the post UTC (ISO 8601) |
Mandatory |
|
paid |
Paid or free article (true = paid, false = free article) |
Optional |
|
tags |
Comma separated tags |
Optional |
|
type |
story / video |
Mandatory |
|
body |
Content of post |
Optional |
Example story
{
"eventType": "post",
"title": "Title of the story",
"relationId": "abc123def567",
"uri": "https://yourdomain.com/post/url/with/post-id/abc123def567/",
"author": "John Doe",
"section": "Sport",
"sectionPath": "/Sport/Football/Champions League",
"timestamp": "2022-05-19T23:59:59+01:00",
"paid": false,
"tags": "tag1,tag2,tag3",
"type": "story",
"body": "post_content"
}
Example video
{
"eventType": "post",
"title": "Title of the video",
"relationId": "abc123def567",
"uri": "https://yourdomain.com/video/url/with/post-id/abc123def567/",
"author": "John Doe",
"section": "Sport",
"sectionPath": "/Sport/Football/Champions League",
"timestamp": "2022-05-19T13:19:05+00:00",
"paid": false,
"tags": "tag1,tag2,tag3",
"type": "video",
"body": "description"
}
Video page views
|
Parameter |
Description |
Mandatory/Optional |
|
eventType |
Indicates type of event, videoPageViews |
Mandatory |
|
relationId |
Unique identifier for the video to which you attribute the views in your website. In case there is no identifier in the uri, send full uri without parameters. |
Optional |
|
uri |
Uri of the website page on which the video is played |
Mandatory |
|
views |
Amount of collected views for video |
Mandatory |
|
timestamp |
Date time of views UTC (ISO 8601) |
Mandatory |
|
platform |
Which platform is used to consume the content |
Optional |
|
propertyId |
Your internal reference of the data group |
Optional |
Example with videoID known by the client
{
"eventType": "videoPageViews",
"views": 45,
"timestamp": "2022-05-19T23:59:59+01:00",
"uri": "visited_page",
"relationId": "123abcd25465",
"platform": "web"
}
Video application views
|
Parameter |
Description |
Mandatory/Optional |
|
eventType |
Indicates type of event, videoAppViews |
Mandatory |
|
relationId |
Unique identifier for the video to which you attribute the views in your app. In case there is no identifier in the uri, send full uri without parameters. |
Optional |
|
uri |
Screen of application on which the video is played |
Mandatory |
|
views |
Amount of collected views for video |
Mandatory |
|
timestamp |
Date time of views UTC (ISO 8601) |
Mandatory |
|
platform |
Which platform is used to consume the content |
Optional |
|
propertyId |
Your internal reference of the data group |
Optional |
Example
{
"eventType": "videoPageViews",
"views": 45,
"timestamp": "2022-05-19T23:59:59+01:00",
"uri": "visited_app_screen",
"relationId": "123abcd25465",
"platform": "app"
}
Conversions
|
Parameter |
Description |
Mandatory/Optional |
|
eventType |
Indicates type of event, conversions |
Mandatory |
|
timestamp |
Date time of the conversion(s) UTC (ISO 8601) |
Mandatory |
|
eventName |
Identifier of the conversion event |
Mandatory |
|
uri |
URL of the page |
Optional |
|
relationId |
Unique identifier for the website page or application to which you attribute the conversion. In case there is no identifier in the uri, send full uri without parameters. |
Optional |
|
platform |
Which platform is used to consume the content |
Optional |
|
propertyId |
Your internal reference of the data group |
Optional |
Example
{
"eventType": "conversions",
"timestamp": "2022-05-19T23:59:59+01:00",
"eventName": "Paywall Window",
"uri": "https://yourdomain.com/post/url/with/post-id/abc123def567/?some=parameter&is=filled",
"relationId": "123abcd25465"
}
Reading Time
|
Parameter |
Description |
Mandatory/Optional |
|
eventType |
Indicates type of event, readingTime |
Mandatory |
|
timestamp |
Date time of views UTC (ISO 8601) |
Mandatory |
|
uri |
URL of the page |
Mandatory |
|
relationId |
Unique identifier for the website page or application to which you attribute the Reading Time. In case there is no identifier in the uri, send the full uri without parameters. |
Optional |
|
channel |
Referral source |
Optional |
|
sessionId |
Unique identifier of visitors session |
Optional |
|
readingTime |
Collected reading time in seconds |
Mandatory |
Example
{
"eventType": "readingTime",
"timestamp": "2022-05-19T23:59:59+01:00",
"uri": "https://yourdomain.com/post/url/with/post-id/abc123def567/?some=parameter&is=filled",
"relationId": "123abcd25465",
"channel": "amp",
"sessionId": "C7BA94110F35ABD48ED406888965E3EF",
"readingTime": "19"
}
Twitter Posts
|
Parameter |
Description |
Mandatory/Optional |
|
eventType |
Indicates type of event, twitterTweets |
Mandatory |
|
timestamp |
Publication date and time of the post, UTC (ISO 8601) |
Mandatory |
|
uri |
URL of the shared story |
Mandatory |
|
relationId |
Unique identifier for the website page or application to which you attribute the Tweet. In case there is no identifier in the uri, send the full uri without parameters. |
Optional |
|
retweets |
Total number of retweets |
Mandatory |
|
likes |
Total number of likes |
Mandatory |
|
tweetId |
Tweet unique identifier |
Optional |
Example
{
"eventType": "twitterTweets",
"timestamp": "2022-05-19T23:59:59+01:00",
"uri": "https://yourdomain.com/post/url/with/post-id/abc123def567/?some=parameter&is=filled",
"relationId": "123abcd25465",
"retweets": "3",
"likes": "9",
"tweetId": "1614328889618186240"
}
Twitter Metrics (retweets and likes)
|
Parameter |
Description |
Mandatory/Optional |
|
eventType |
Indicates type of event, twitterMetrics |
Mandatory |
|
timestamp |
Date time of engagement UTC (ISO 8601) |
Mandatory |
|
uri |
URL of the shared story |
Mandatory |
|
relationId |
Unique identifier for shared story |
Optional |
|
retweets |
Total number of retweets |
Mandatory |
|
likes |
Total number of likes |
Mandatory |
|
tweetId |
Tweet unique identifier |
Optional |
Example
{
"eventType": "twitterMetrics",
"timestamp": "2022-05-19T23:59:59+01:00",
"uri": "https://yourdomain.com/post/url/with/post-id/abc123def567/?some=parameter&is=filled",
"relationId": "123abcd25465",
"retweets": "3",
"likes": "9",
"tweetId": "1614328889618186240"
}
Homepage
Homepage events contain information about the stories, currently on the homepage when sending the events.
|
Parameter |
Description |
Mandatory/Optional |
|
eventType |
Indicates type of event, homepage |
Mandatory |
|
timestamp |
Date time of publishing on homepage UTC (ISO 8601) |
Mandatory |
|
uri |
Uri of the website page or application screen to which you attribute the position on the homepage. |
Optional |
|
relationId |
Unique identifier for the website page or application to which you attribute the position on the homepage. In case there is no identifier in the uri, send full uri without parameters. |
Optional |
Example
{
"eventType": "homepage",
"timestamp": "2022-05-19T23:59:59+01:00",
"uri": "https://yourdomain.com/post/url/with/post-id/abc123def567/?some=parameter&is=filled",
"relationId": "123abcd25465"
}
Segment
|
Parameter |
Description |
Mandatory/Optional |
|
eventType |
Indicates type of event, segment |
Mandatory |
|
segmentId |
Segment identifier |
Mandatory |
|
segmentName |
Segment name |
Mandatory |
|
components |
Components configuration in JSON format |
Optional |
Example
{
"eventType": "segment",
"segmentId": "loggedInType",
"segmentName": "Logged in or not"
"components": [
{
"color": "#FFB528",
"value": "loggedIn",
"label": "Logged in user"
},
{
"color": "#220189",
"value": "notLoggedIn",
"label": "Not logged in user"
}
]
}
Segment events
|
Parameter |
Description |
Mandatory/Optional |
|
eventType |
Indicates type of event, segmentEvents |
Mandatory |
|
propertyId |
Your internal reference of the data group |
Optional |
|
uri |
URL of the viewed application screen |
Mandatory |
|
relationId |
Unique identifier for post, or path of the URI compiled by the client |
Optional |
|
views |
Amount of collected views for post |
Mandatory |
|
timestamp |
Date time for collected views UTC (ISO 8601) |
Mandatory |
|
segmentId |
Segment identifier |
Mandatory |
|
segmentValue |
Event value |
Mandatory |
Example
{
"eventType": "segmentEvents",
"propertyId": "snowplowSite1",
"uri": "https://yourdomain.com/post/url/with/post-id/abc123def567/?some=parameter&is=filled",
"relationId": "abc123def567",
"views": 140,
"timestamp": "2022-05-19T23:59:59+01:00",
"segmentId": "loggedInType",
"segmentValue": "loggedIn"
}
Newsletter
|
Parameter |
Description |
Mandatory/Optional |
|
eventType |
Indicates type of event, newsletter |
Mandatory |
|
timestamp |
Date time of sending the newsletter UTC (ISO 8601) |
Mandatory |
|
uri |
Uri of the website page or application screen to which you attribute the position in the newsletter |
Optional |
|
relationId |
Unique identifier for the website page or application to which you attribute the newsletter. In case there is no identifier in the uri, send full uri without parameters. |
Mandatory |
|
messageId |
Unique identifier of newsletter message |
Optional |
|
messageSubject |
Newsletter message subject |
Optional |
Example
{
"eventType": "newsletter",
"timestamp": "2022-05-19T23:59:59+01:00",
"uri": "https://yourdomain.com/post/url/with/post-id/abc123def567/?some=parameter&is=filled",
"relationId": "123abcd25465",
"messageId": "1ab7ce2cfeff2581b3e3acef5d67674e2770141f6c217667af",
"messageSubject": "Weekend newsletter: John catches the biggest fish of town"
}
Push notification
|
Parameter |
Description |
Mandatory/Optional |
|
eventType |
Indicates type of event, pushMessage |
Mandatory |
|
timestamp |
Date time of sending push UTC (ISO 8601) |
Mandatory |
|
title |
Title of the post |
Mandatory |
|
uri |
Uri of the website page or application screen to which you attribute the conversion |
Optional |
|
relationId |
Unique identifier for the website page or application to which you attribute the push. In case there is no identifier in the uri, send full uri without parameters. |
Optional |
Example
{
"eventType": "pushMessage",
"timestamp": "2022-05-19T23:59:59+01:00",
"title": "John catches the biggest fish of the year",
"uri": "https://yourdomain.com/post/url/with/post-id/abc123def567/?some=parameter&is=filled",
"relationId": "123abcd25465"
}