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 renders

  • move : Clicks on widget slider move or next page request

  • upload_click : Clicks on the upload photo button

  • filter_click : Clicks on the filter button

  • view_all : Clicks on the button that opens the Gallery widget from a Carousel widget

GET

/track/widget/{instance_id}/category/{category_id}/{action}{format}{?analytics_id,pics,ab_testing,segments}

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

string (required)

Hash identifying the current widget instance

category_id

int (required)

The id of the category

action

string (required)

The action to track, the available options are: render, move, upload_click, filter_click or view_all

format

string (optional) Example: .json

The content type of the response, it can be either .json or .gif depending if you prefer a JSON or a 1x1 GIF as response

analytics_id

string (required)

Value identifying the current user

pics

int (required)

Number of media the widget is displaying

ab_testing

int (optional)

AB Testing experiment number. Do not include this param if AB testing is disabled

segments

array (optional) Example: segments[]=country:US&segments[]=section:abc

key:value pairs will be used to group and display the analytics results (segmentation), you can send as many pairs as needed, Only one value for each key is allowed

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 renders

  • move : Clicks on widget slider move or next page request

  • upload_click : Clicks on the upload photo button

  • filter_click : Clicks on the filter button

  • view_all : Clicks on the button that opens the Gallery widget from a Carousel widget

GET

/track/widget/{instance_id}/stream/{stream_id}/{action}{format}{?analytics_id,pics,ab_testing,segments}

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

string (required)

Hash identifying the current widget instance

stream_id

int (required)

The id of the stream

action

string (required)

The action to track, the available options are: render, move, upload_click, filter_click or view_all

format

string (optional) Example: .json

The content type of the response, it can be either .json or .gif depending if you prefer a JSON or a 1x1 GIF as response

analytics_id

string (required)

Value identifying the current user

pics

int (required)

Number of media the widget is displaying

ab_testing

int (optional)

AB Testing experiment number. Do not include this param if AB testing is disabled

segments

array (optional) Example: segments[]=country:US&segments[]=section:abc

key:value pairs will be used to group and display the analytics results (segmentation), you can send as many pairs as needed, Only one value for each key is allowed

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 renders

  • move : Clicks on widget slider move or next page request

  • upload_click : Clicks on the upload photo button

  • filter_click : Clicks on the filter button

  • view_all : Clicks on the button that opens the Gallery widget from a Carousel widget

GET

/track/widget/{instance_id}/best/{action}{format}{?analytics_id,pics,ab_testing,segments}

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

string (required)

Hash identifying the current widget instance

action

string (required)

The action to track, the available options are: render, move, upload_click, filter_click or view_all

format

string (optional) Example: .json

The content type of the response, it can be either .json or .gif depending if you prefer a JSON or a 1x1 GIF as response

analytics_id

string (required)

Value identifying the current user

pics

int (required)

Number of media the widget is displaying

ab_testing

int (optional)

AB Testing experiment number. Do not include this param if AB testing is disabled

segments

array (optional) Example: segments[]=country:US&segments[]=section:abc

key:value pairs will be used to group and display the analytics results (segmentation), you can send as many pairs as needed, Only one value for each key is allowed

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

/track/widget/{instance_id}/stream/not_found/render{format}{?analytics_id,ab_testing,segments}

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

string (required)

Hash identifying the current widget instance

format

string (optional) Example: .json

The content type of the response, it can be either .json or .gif depending if you prefer a JSON or a 1x1 GIF as response

analytics_id

string (required)

Value identifying the current user

ab_testing

int (optional)

AB Testing experiment number. Do not include this param if AB testing is disabled

segments

array (optional) Example: segments[]=country:US&segments[]=section:abc

key:value pairs will be used to group and display the analytics results (segmentation), you can send as many pairs as needed, Only one value for each key is allowed

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 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

  • play_click : Play clicks on media

GET

/track/widget/{instance_id}/category/{category_id}/media/{media_id}/{action}{format}{?analytics_id,pics,ab_testing,segments}

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

string (required)

Hash identifying the current widget instance

category_id

int (required)

The id of the category

media_id

int (required)

The id of the media

action

string (required)

The action to track, the available options are: render, view, move, click, close or play_click

format

string (optional) Example: .json

The content type of the response, it can be either .json or .gif depending if you prefer a JSON or a 1x1 GIF as response

analytics_id

string (required)

Value identifying the current user

pics

int (required)

Number of media the widget is displaying

ab_testing

int (optional)

AB Testing experiment number. Do not include this param if AB testing is disabled

segments

array (optional) Example: segments[]=country:US&segments[]=section:abc

key:value pairs will be used to group and display the analytics results (segmentation), you can send as many pairs as needed, Only one value for each key is allowed

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 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

  • play_click : Play clicks on media

GET

/track/widget/{instance_id}/stream/{stream_id}/media/{media_id}/{action}{format}{?analytics_id,pics,ab_testing,segments}

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

string (required)

Hash identifying the current widget instance

stream_id

int (required)

The id of the stream

media_id

int (required)

The id of the media

action

string (required)

The action to track, the available options are: render, view, move, click, close or play_click

format

string (optional) Example: .json

The content type of the response, it can be either .json or .gif depending if you prefer a JSON or a 1x1 GIF as response

analytics_id

string (required)

Value identifying the current user

pics

int (required)

Number of media the widget is displaying

ab_testing

int (optional)

AB Testing experiment number. Do not include this param if AB testing is disabled

segments

array (optional) Example: segments[]=country:US&segments[]=section:abc

key:value pairs will be used to group and display the analytics results (segmentation), you can send as many pairs as needed, Only one value for each key is allowed

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 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

  • play_click : Play clicks on media

GET

/track/widget/{instance_id}/best/media/{media_id}/{action}{format}{?analytics_id,pics,ab_testing,segments}

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

string (required)

Hash identifying the current widget instance

media_id

int (required)

The id of the media

action

string (required)

The action to track, the available options are: render, view, move, click, close or play_click

format

string (optional) Example: .json

The content type of the response, it can be either .json or .gif depending if you prefer a JSON or a 1x1 GIF as response

analytics_id

string (required)

Value identifying the current user

pics

int (required)

Number of media the widget is displaying

ab_testing

int (optional)

AB Testing experiment number. Do not include this param if AB testing is disabled

segments

array (optional) Example: segments[]=country:US&segments[]=section:abc

key:value pairs will be used to group and display the analytics results (segmentation), you can send as many pairs as needed, Only one value for each key is allowed

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

/track/widget/{instance_id}/category/{category_id}/media/{media_id}/shop{format}{?analytics_id,pics,ab_testing,redirect_url,segments}

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

string (required)

Hash identifying the current widget instance

category_id

int (required)

The id of the category

media_id

int (required)

The id of the media

format

string (optional) Example: .json

The content type of the response, it can be either .json or .gif depending if you prefer a JSON or a 1x1 GIF as response

analytics_id

string (required)

Value identifying the current user

pics

int (required)

Number of media the widget is displaying

ab_testing

int (optional)

AB Testing experiment number. Do not include this param if AB testing is disabled

redirect_url

string (optional)

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

array (optional) Example: segments[]=country:US&segments[]=section:abc

key:value pairs will be used to group and display the analytics results (segmentation), you can send as many pairs as needed, Only one value for each key is allowed

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

/track/widget/{instance_id}/stream/{stream_id}/media/{media_id}/shop{format}{?analytics_id,pics,ab_testing,redirect_url,segments}

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

string (required)

Hash identifying the current widget instance

stream_id

int (required)

The id of the stream

media_id

int (required)

The id of the media

format

string (optional) Example: .json

The content type of the response, it can be either .json or .gif depending if you prefer a JSON or a 1x1 GIF as response

analytics_id

string (required)

Value identifying the current user

pics

int (required)

Number of media the widget is displaying

ab_testing

int (optional)

AB Testing experiment number. Do not include this param if AB testing is disabled

redirect_url

string (optional)

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

array (optional) Example: segments[]=country:US&segments[]=section:abc

key:value pairs will be used to group and display the analytics results (segmentation), you can send as many pairs as needed, Only one value for each key is allowed

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

/track/widget/{instance_id}/best/media/{media_id}/shop{format}{?analytics_id,pics,ab_testing,redirect_url,segments}

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

string (required)

Hash identifying the current widget instance

media_id

int (required)

The id of the media

format

string (optional) Example: .json

The content type of the response, it can be either .json or .gif depending if you prefer a JSON or a 1x1 GIF as response

analytics_id

string (required)

Value identifying the current user

pics

int (required)

Number of media the widget is displaying

ab_testing

int (optional)

AB Testing experiment number. Do not include this param if AB testing is disabled

redirect_url

string (optional)

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

array (optional) Example: segments[]=country:US&segments[]=section:abc

key:value pairs will be used to group and display the analytics results (segmentation), you can send as many pairs as needed, Only one value for each key is allowed

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

/track/transaction/{transaction_id}/checkout{format}{?analytics_id,products,segments,currency_code,referrer}

Example URI

GET /track/transaction/transaction_id/checkout.json?analytics_id=&products=products[]=product-123:120.50&segments=segments[]=country:US&segments[]=section:abc&currency_code=EUR&referrer=referrer=https:/domain.com/checkout

URI Parameters

transaction_id

string (required)

The Id of the transaction, all products in the same checkout should have the same transaction

format

string (optional) Example: .json

The content type of the response, it can be either .json or .gif depending if you prefer a JSON or a 1x1 GIF as response

analytics_id

string (required)

Value identifying the current user

products

array (required) Example: products[]=product-123:120.50

Array containing the products purchased in the transaction and the amount for each product. The format is product_id:amount.

segments

array (optional) Example: segments[]=country:US&segments[]=section:abc

Segmentation information, key:value pairs will be used to group and display the results, you can send ad many pairs as needed, Only one value for each key is allowed

currency_code

string (optional) Default: USD Example: EUR

The ISO 4217 Alphabetic code of the currency.

referrer

string (optional) Example: referrer=https://domain.com/checkout

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

Did this answer your question?