The Analytics Tracking API allows you to track users interactions with UGC content through our widgets.
These interactions can be tracked as events. Media views, video plays, product checkouts are examples of events you might want to track.
Currently the API supports the following events on widgets:
Render: When a widget is rendered
Move: Clicks on slider move or new page loaded
Upload click: Clicks on the upload photo button
Filter click: Clicks on the filter button
View all: Clicks on the button that opens a Gallery widget from a Carousel widget
Also supports the following events on media:
Render: When the media thumbnail is seen in the browser viewport
View: When the media is opened in the modal (viewer)
Move: When you move to the next/prev media
Click: Clicks on media
Close: Media close clicks
Shop this product: Click on ‘Shop this product’ link on media (which redirects the user to the PDP)
Play click: Play clicks on media
Finally, we also should track the purchase events:
Checkout: Track when a product is purchased by a user in the customer website.
In some cases, you need to know whether an event was successfully sent to the Tracking API. If you have your browser’s developers tools open when you load a page that uses Olapic widgets, you can see the events being sent in the network tab. Look for requests sent to data.photorank.me
. For more information, see the sections Request and Response format.
Once you have successfully implemented the Analytics tracking, it may take up to 24 hours for data appear in your Analytics reports.
Request
All tracking endpoints use the GET
method.
GET / HTTP/1.1
Host: data.photorank.me
Accept: application/json
Authentication
Tracking methods require a public token to be accessible.
GET /?auth_token=5df38d HTTP/1.1
Host: data.photorank.me
Response format
All the HTTP responses include a metadata
section and all non-error responses also contains data
sections.
The metadata
section includes the HTTP status code, the messages associated to the status code, and the version.
The data
section contains the timestamp
and the analytics_id
used to track the event.
{
metadata: {
code: 200,
message: "OK",
version: "v1.0"
},
data:
{
"timestamp": "2014-06-25 15:19:08.3000",
"analytics_id": "12345"
}
}
Status Codes
Any of the following status codes should be expected for the API client.
Status | Message | Description |
200 | OK | This is the standard response for successful requests. |
302 | Found | A response with this status code will additionally provide a URL in the Location header field where the user should be redirected. |
304 | Not Modified | The server responses with this status code when the client has performed a conditional GET. It indicates the content the client previously received is still valid. |
400 | Bad Request | The request cannot be fulfilled due to bad formed URI or a missing parameter. The request should not be repeated without modifications. |
403 | Forbidden | The servers refuses to return the content due an Authentication issue. The client should not repeat the request unless proper credentials are used. |
404 | Not Found | The server has not found any resource matching the Request-URI or the resource is currently unavailable. The request could be repeated. |
409 | Conflict | The request could not be completed due to a conflict with the current state of the resource. |
500 | Internal Server Error | The server encountered an unexpected condition which prevented it from fulfilling the request. It could be a temporary issue. |
503 | Service Unavailable | The server is currently unable to handle the request due a programed maintenance. The inactivity period will be informed with proper advance via other channels. |
Widget track
CATEGORY WIDGET ACTION
Track an action over a category widget, available actions are:
render
: When the widget rendersmove
: Clicks on widget slider move or next page requestupload_click
: Clicks on the upload photo buttonfilter_click
: Clicks on the filter buttonview_all
: Clicks on the button that opens the Gallery widget from a Carousel widget
GET |
|
Example URI
GET /track/widget/instance_id/category/category_id/action.json?analytics_id=&pics=&ab_testing=&segments=segments[]=country:US&segments[]=section:abc
URI Parameters
instance_id |
Hash identifying the current widget instance |
category_id
|
The id of the category |
action
|
The action to track, the available options are: |
format
|
The content type of the response, it can be either |
analytics_id
|
Value identifying the current user |
pics
|
Number of media the widget is displaying |
ab_testing
|
AB Testing experiment number. Do not include this param if AB testing is disabled |
segments
|
|
Response 200
Headers
Content-Type: application/json
Body
{
"metadata": {
"code": 200,
"message": "OK",
"version": "v1.0"
},
"data": {
"timestamp": [timestamp_value],
"analytics_id": [analytics_id]
}
}
Response 400
Headers
Content-Type: application/json
Body
[
{
"error": "Invalid params"
}
]
STREAM WIDGET ACTION
Track an action over a stream widget, available actions are:
render
: When the widget rendersmove
: Clicks on widget slider move or next page requestupload_click
: Clicks on the upload photo buttonfilter_click
: Clicks on the filter buttonview_all
: Clicks on the button that opens the Gallery widget from a Carousel widget
GET |
|
Example URI
GET
/track/widget/instance_id/stream/stream_id/action.json?analytics_id=&pics=&ab_testing=&segments=segments[]=country:US&segments[]=section:abc
URI Parameters
instance_id |
Hash identifying the current widget instance |
stream_id |
The id of the stream |
action |
The action to track, the available options are: |
format |
The content type of the response, it can be either |
analytics_id |
Value identifying the current user |
pics |
Number of media the widget is displaying |
ab_testing |
AB Testing experiment number. Do not include this param if AB testing is disabled |
segments |
|
Response 200
Headers
Content-Type: application/json
Body
{
"metadata": {
"code": 200,
"message": "OK",
"version": "v1.0"
},
"data": {
"timestamp": [timestamp_value],
"analytics_id": [analytics_id]
}
}
Response 400
BEST PHOTOS WIDGET ACTION
Track an action over a best photos widget, available actions are:
render
: When the widget rendersmove
: Clicks on widget slider move or next page requestupload_click
: Clicks on the upload photo buttonfilter_click
: Clicks on the filter buttonview_all
: Clicks on the button that opens the Gallery widget from a Carousel widget
GET |
|
Example URI
GET
/track/widget/instance_id/best/action.json?analytics_id=&pics=&ab_testing=&segments=segments[]=country:US&segments[]=section:abc
URI Parameters
instance_id |
Hash identifying the current widget instance |
action |
The action to track, the available options are: |
format |
The content type of the response, it can be either |
analytics_id |
Value identifying the current user |
pics |
Number of media the widget is displaying |
ab_testing |
AB Testing experiment number. Do not include this param if AB testing is disabled |
segments |
|
Response 200
Headers
Content-Type: application/json
Body
{
"metadata": {
"code": 200,
"message": "OK",
"version": "v1.0"
},
"data": {
"timestamp": [timestamp_value],
"analytics_id": [analytics_id]
}
}
Response 400
STREAM NOT FOUND WIDGET RENDER
Track a stream widget render event where the stream couldn’t be found (this usually means the widget get rendered without any picture on it)
GET |
|
Example URI
GET
/track/widget/instance_id/stream/not_found/render.json?analytics_id=&ab_testing=&segments=segments[]=country:US&segments[]=section:abc
URI Parameters
instance_id |
Hash identifying the current widget instance |
format |
The content type of the response, it can be either |
analytics_id |
Value identifying the current user |
ab_testing |
AB Testing experiment number. Do not include this param if AB testing is disabled |
segments |
|
Response 200
Headers
Content-Type: application/json
Body
{
"metadata": {
"code": 200,
"message": "OK",
"version": "v1.0"
},
"data": {
"timestamp": [timestamp_value],
"analytics_id": [analytics_id]
}
}
Response 400
Media Track
CATEGORY WIDGET MEDIA ACTION
Track the following action over a media in a category widget:
render
: When the media thumbnail is seen in the browser viewportview
: When the media is opened in the modal (viewer)move
: When you move to the next/prev mediaclick
: Clicks on mediaclose
: Media close clicksplay_click
: Play clicks on media
GET |
|
Example URI
GET
/track/widget/instance_id/category/category_id/media/media_id/action.json?analytics_id=&pics=&ab_testing=&segments=segments[]=country:US&segments[]=section:abc
URI Parameters
instance_id |
Hash identifying the current widget instance |
category_id |
The id of the category |
media_id |
The id of the media |
action |
The action to track, the available options are: |
format |
The content type of the response, it can be either |
analytics_id |
Value identifying the current user |
pics |
Number of media the widget is displaying |
ab_testing |
AB Testing experiment number. Do not include this param if AB testing is disabled |
segments |
|
Response 200
Headers
Content-Type: application/json
Body
{
"metadata": {
"code": 200,
"message": "OK",
"version": "v1.0"
},
"data": {
"timestamp": [timestamp_value],
"analytics_id": [analytics_id]
}
}
Response 400
STREAM WIDGET MEDIA ACTION
Track the following action over media in a stream widget:
render
: When the media thumbnail is seen in the browser viewportview
: When the media is opened in the modal (viewer)move
: When you move to the next/prev mediaclick
: Clicks on mediaclose
: Media close clicksplay_click
: Play clicks on media
GET |
|
Example URI
GET
/track/widget/instance_id/stream/stream_id/media/media_id/action.json?analytics_id=&pics=&ab_testing=&segments=segments[]=country:US&segments[]=section:abc
URI Parameters
instance_id |
Hash identifying the current widget instance |
stream_id |
The id of the stream |
media_id |
The id of the media |
action |
The action to track, the available options are: |
format |
The content type of the response, it can be either |
analytics_id |
Value identifying the current user |
pics |
Number of media the widget is displaying |
ab_testing |
AB Testing experiment number. Do not include this param if AB testing is disabled |
segments |
|
Response 200
Headers
Content-Type: application/json
Body
{
"metadata": {
"code": 200,
"message": "OK",
"version": "v1.0"
},
"data": {
"timestamp": [timestamp_value],
"analytics_id": [analytics_id]
}
}
Response 400
BEST PHOTOS WIDGET MEDIA ACTION
Track the following action over media in a best photos widget:
render
: When the media thumbnail is seen in the browser viewportview
: When the media is opened in the modal (viewer)move
: When you move to the next/prev mediaclick
: Clicks on mediaclose
: Media close clicksplay_click
: Play clicks on media
GET |
|
Example URI
GET
/track/widget/instance_id/best/media/media_id/action.json?analytics_id=&pics=&ab_testing=&segments=segments[]=country:US&segments[]=section:abc
URI Parameters
instance_id |
Hash identifying the current widget instance |
media_id |
The id of the media |
action |
The action to track, the available options are: |
format |
The content type of the response, it can be either |
analytics_id |
Value identifying the current user |
pics |
Number of media the widget is displaying |
ab_testing |
AB Testing experiment number. Do not include this param if AB testing is disabled |
segments |
|
Response 200
Headers
Content-Type: application/json
Body
{
"metadata": {
"code": 200,
"message": "OK",
"version": "v1.0"
},
"data": {
"timestamp": [timestamp_value],
"analytics_id": [analytics_id]
}
}
Response 400
CATEGORY WIDGET "SHOP THIS PRODUCT" CLICK
Track clicks on ‘Shop this product’ links on a media from a category widget
GET |
|
Example URI
GET
/track/widget/instance_id/category/category_id/media/media_id/shop.json?analytics_id=&pics=&ab_testing=&redirect_url=&segments=segments[]=country:US&segments[]=section:abc
URI Parameters
instance_id |
Hash identifying the current widget instance |
category_id |
The id of the category |
media_id |
The id of the media |
format |
The content type of the response, it can be either |
analytics_id |
Value identifying the current user |
pics |
Number of media the widget is displaying |
ab_testing |
AB Testing experiment number. Do not include this param if AB testing is disabled |
redirect_url |
URL of the page it’s going to be redirected (the status code of this response will be 302 and a Location header is going to be added to redirect the user). If this parameter if omitted the status code of the response will be 200. |
segments |
|
Response 200
Headers
Content-Type: application/json
Body
{
"metadata": {
"code": 200,
"message": "OK",
"version": "v1.0"
},
"data": {
"timestamp": [timestamp_value],
"analytics_id": [analytics_id]
}
}
Response 400
Response 302
Headers
Content-Type: application/json
STREAM WIDGET "SHOP THIS PRODUCT" CLICK
Track clicks on ‘Shop this product’ links on media from a stream widget
GET |
|
Example URI
GET
/track/widget/instance_id/stream/stream_id/media/media_id/shop.json?analytics_id=&pics=&ab_testing=&redirect_url=&segments=segments[]=country:US&segments[]=section:abc
URI ParametersHide
instance_id |
Hash identifying the current widget instance |
stream_id |
The id of the stream |
media_id |
The id of the media |
format |
The content type of the response, it can be either |
analytics_id |
Value identifying the current user |
pics |
Number of media the widget is displaying |
ab_testing |
AB Testing experiment number. Do not include this param if AB testing is disabled |
redirect_url |
URL of the page it’s going to be redirected (the status code of this response will be 302 and a Location header is going to be added to redirect the user). If this parameter if omitted the status code of the response will be 200. |
segments |
|
Response 200
Headers
Content-Type: application/json
Body
{
"metadata": {
"code": 200,
"message": "OK",
"version": "v1.0"
},
"data": {
"timestamp": [timestamp_value],
"analytics_id": [analytics_id]
}
}
Response 400
Response 302
Headers
Content-Type: application/json
BEST PHOTOS WIDGET "SHOP THIS PRODUCT" CLICK
Track clicks on ‘Shop this product’ links on media from a ‘best photos’ widget
GET |
|
Example URI
GET
/track/widget/instance_id/best/media/media_id/shop.json?analytics_id=&pics=&ab_testing=&redirect_url=&segments=segments[]=country:US&segments[]=section:abc
URI Parameters
instance_id |
Hash identifying the current widget instance |
media_id |
The id of the media |
format |
The content type of the response, it can be either |
analytics_id |
Value identifying the current user |
pics |
Number of media the widget is displaying |
ab_testing |
AB Testing experiment number. Do not include this param if AB testing is disabled |
redirect_url |
URL of the page it’s going to be redirected (the status code of this response will be 302 and a Location header is going to be added to redirect the user). If this parameter if omitted the status code of the response will be 200. |
segments |
|
Response 200
Headers
Content-Type: application/json
Body
{
"metadata": {
"code": 200,
"message": "OK",
"version": "v1.0"
},
"data": {
"timestamp": [timestamp_value],
"analytics_id": [analytics_id]
}
}
Response 400
Response 302
Headers
Content-Type: application/json
Purchase Track
CHECKOUT
Track checkouts, this requires a transaction id and an array of products and their amount.
GET |
|
Example URI
GET
/track/transaction/transaction_id/checkout.json?analytics_id=&products=products[]=product-123:120.50&segments=segments[]=country:US&segments[]=section:abc¤cy_code=EUR&referrer=referrer=https:/domain.com/checkout
URI Parameters
transaction_id |
The Id of the transaction, all products in the same checkout should have the same transaction |
format |
The content type of the response, it can be either |
analytics_id |
Value identifying the current user |
products |
Array containing the products purchased in the transaction and the amount for each product. The format is |
segments |
Segmentation information, |
currency_code |
The ISO 4217 Alphabetic code of the currency. |
referrer |
The URL of the checkout confirmation page |
Response 200
Headers
Content-Type: application/json
Body
{
"metadata": {
"code": 200,
"message": "OK",
"version": "v1.0"
},
"data": {
"timestamp": [timestamp_value],
"analytics_id": [analytics_id]
}
}
Response 400