Adways APIs documentation

HVPublish

An "HVPublish" entity is a "publication", a consolidated version (a kind of uneditable snapshot) of an interactive project. The front final user experience script does not load a "HVProjectInfo" entity but a "HVPublish" entity (see the "HVLoadPublication" RPC of the current API). The relation between a "HVPublish" and a "HVProjectInfo" is the same as the one between a ".doc" (Microsoft Word as the Adways Studio) and a ".pdf" (Adobe Reader as the "interactive engine"). That means: it is possible to publish a project mutltiple times under different publication ids; a publication won't change if the project is edited after; and finally, going from a project to a publication is possible, but rebuilding a project from a publication won't give back the original project. Note that a publication has a durability and an expiration date.

Fields

Field	Description	Required
name	The publication's name.	YES
hv_save	The "HVSave" entity's id used to create the publication. If an "HVProject" entity's id is provided, this field isn't required: in this case, the last project's save is used.	NO
hv_project	The "HVProject" entity's id used to create the publication. If a "HVSave" entity's id is provided this field isn't required.	NO
durability	Time in month until the publication expires. Available duration are: 2, 6, 12, 24, 48, 120 months. Default value used if empty, missing or bad value: 24 month	NO
media	The project's "Media" id. The Media's id of the video on top of which the interactivity is created.	NO
description	Description from entry	NO

GET /hv-publish

Loads a collection of available entities. The loaded collection is paginated. An optional "search" parameter is available to filter the result on the entities' name and id (ex.: "//hv-publish?search=SearchValue").

Request

EndPoint

https://services.adways.com/hv-publish

Headers

Header	Value
Accept	application/vnd.hv-publish.v1+json application/hal+json application/json

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
200: OK
403: Forbidden

Headers

Header	Value
Content-Type	application/vnd.hv-publish.v1+json application/hal+json application/json
Allow	Comma-separated list of all HTTP methods allowed

Body

{
    "_links": {
        "self": {
            "href": "/hv-publish"
        },
        "first": {
            "href": "/hv-publish?page={page}"
        },
        "prev": {
            "href": "/hv-publish?page={page}"
        },
        "next": {
            "href": "/hv-publish?page={page}"
        },
        "last": {
            "href": "/hv-publish?page={page}"
        }
    },
    "_embedded": {
        "collection": [
            {
                "id": "",
                "created": "",
                "author": "",
                "updated": "",
                "updator": "",
                "level": "",
                "state": "",
                "name": "The publication's name.",
                "hv_save": "The "HVSave" entity's id used to create the publication. If an "HVProject" entity's id is provided, this field isn't required: in this case, the last project's save is used.",
                "hv_project": "The "HVProject" entity's id used to create the publication. If a "HVSave" entity's id is provided this field isn't required.",
                "durability": "Time in month until the publication expires. Available duration are:\r\n2, 6, 12, 24, 48, 120 months.\r\n\r\nDefault value used if empty, missing or bad value: 24 month",
                "media": "The project's "Media" id. The Media's id of the video on top of which the interactivity is created.",
                "description": "Description from entry",
                "_links": {
                    "self": {
                        "href": "/hv-publish[/:hv_publish_id]"
                    }
                }
            }
        ]
    }
}

POST /hv-publish

Creates an entity in HVPublish. Required fields are in the API fields description above. Note that on success, the returned http status is "201, Created".

Request

EndPoint

https://services.adways.com/hv-publish

Headers

Header	Value
Accept	application/vnd.hv-publish.v1+json application/hal+json application/json
Content-Type	application/vnd.hv-publish.v1+json application/json

Body

{
   "name": "The name of the publication",
   "hv_save": "HVSave to use to create the publication.
This value is not required if you have given an HVProject id. If so, it's the last save which will be used.",
   "hv_project": "HVProject to use to create the publication.
This value is not required if you have given an HVSave id. 

If you just give an HVProject id, it will be the last saved data which will be used.",
   "durability": "Time in month until the publication expires. Available possibilities are:
2, 6, 12, 24, 48, 120

Default value used if empty, missing or bad value: 24 month",
   "media": "Media id to use for this project"
}

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
201: Created
400: Client Error
422: Unprocessable Entity
403: Forbidden

Headers

Header	Value
Content-Type	application/vnd.hv-publish.v1+json application/hal+json application/json
Allow	Comma-separated list of all HTTP methods allowed

Body

{
    "id": "",
    "created": "",
    "author": "",
    "updated": "",
    "updator": "",
    "level": "",
    "state": "",
    "name": "The publication's name.",
    "hv_save": "The "HVSave" entity's id used to create the publication. If an "HVProject" entity's id is provided, this field isn't required: in this case, the last project's save is used.",
    "hv_project": "The "HVProject" entity's id used to create the publication. If a "HVSave" entity's id is provided this field isn't required.",
    "durability": "Time in month until the publication expires. Available duration are:\r\n2, 6, 12, 24, 48, 120 months.\r\n\r\nDefault value used if empty, missing or bad value: 24 month",
    "media": "The project's "Media" id. The Media's id of the video on top of which the interactivity is created.",
    "description": "Description from entry",
    "_links": {
        "self": {
            "href": "/hv-publish[/:hv_publish_id]"
        }
    }
}

GET /hv-publish[/:hv_publish_id]

Loads the entity with the given id.

Request

EndPoint

https://services.adways.com/hv-publish[/:hv_publish_id]

Headers

Header	Value
Accept	application/vnd.hv-publish.v1+json application/hal+json application/json

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
200: OK
404: Not Found
403: Forbidden

Headers

Header	Value
Content-Type	application/vnd.hv-publish.v1+json application/hal+json application/json
Allow	Comma-separated list of all HTTP methods allowed

Body

{
    "id": "",
    "created": "",
    "author": "",
    "updated": "",
    "updator": "",
    "level": "",
    "state": "",
    "name": "The publication's name.",
    "hv_save": "The "HVSave" entity's id used to create the publication. If an "HVProject" entity's id is provided, this field isn't required: in this case, the last project's save is used.",
    "hv_project": "The "HVProject" entity's id used to create the publication. If a "HVSave" entity's id is provided this field isn't required.",
    "durability": "Time in month until the publication expires. Available duration are:\r\n2, 6, 12, 24, 48, 120 months.\r\n\r\nDefault value used if empty, missing or bad value: 24 month",
    "media": "The project's "Media" id. The Media's id of the video on top of which the interactivity is created.",
    "description": "Description from entry",
    "_links": {
        "self": {
            "href": "/hv-publish[/:hv_publish_id]"
        }
    }
}

PATCH /hv-publish[/:hv_publish_id]

Updates a subset of the entity with the given id (only the modified fields are required).

Request

EndPoint

https://services.adways.com/hv-publish[/:hv_publish_id]

Headers

Header	Value
Accept	application/vnd.hv-publish.v1+json application/hal+json application/json
Content-Type	application/vnd.hv-publish.v1+json application/json

Body

{
   "name": "The name of the publication",
   "hv_save": "HVSave to use to create the publication.
This value is not required if you have given an HVProject id. If so, it's the last save which will be used.",
   "hv_project": "HVProject to use to create the publication.
This value is not required if you have given an HVSave id. 

If you just give an HVProject id, it will be the last saved data which will be used.",
   "durability": "Time in month until the publication expires. Available possibilities are:
2, 6, 12, 24, 48, 120

Default value used if empty, missing or bad value: 24 month",
   "media": "Media id to use for this project"
}

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
200: OK
404: Not Found
400: Client Error
422: Unprocessable Entity
403: Forbidden

Headers

Header	Value
Content-Type	application/vnd.hv-publish.v1+json application/hal+json application/json
Allow	Comma-separated list of all HTTP methods allowed

Body

{
    "id": "",
    "created": "",
    "author": "",
    "updated": "",
    "updator": "",
    "level": "",
    "state": "",
    "name": "The publication's name.",
    "hv_save": "The "HVSave" entity's id used to create the publication. If an "HVProject" entity's id is provided, this field isn't required: in this case, the last project's save is used.",
    "hv_project": "The "HVProject" entity's id used to create the publication. If a "HVSave" entity's id is provided this field isn't required.",
    "durability": "Time in month until the publication expires. Available duration are:\r\n2, 6, 12, 24, 48, 120 months.\r\n\r\nDefault value used if empty, missing or bad value: 24 month",
    "media": "The project's "Media" id. The Media's id of the video on top of which the interactivity is created.",
    "description": "Description from entry",
    "_links": {
        "self": {
            "href": "/hv-publish[/:hv_publish_id]"
        }
    }
}

PUT /hv-publish[/:hv_publish_id]

Updates the entire entity with the given id (all the fields are required).

Request

EndPoint

https://services.adways.com/hv-publish[/:hv_publish_id]

Headers

Header	Value
Accept	application/vnd.hv-publish.v1+json application/hal+json application/json
Content-Type	application/vnd.hv-publish.v1+json application/json

Body

{
   "name": "The name of the publication",
   "hv_save": "HVSave to use to create the publication.
This value is not required if you have given an HVProject id. If so, it's the last save which will be used.",
   "hv_project": "HVProject to use to create the publication.
This value is not required if you have given an HVSave id. 

If you just give an HVProject id, it will be the last saved data which will be used.",
   "durability": "Time in month until the publication expires. Available possibilities are:
2, 6, 12, 24, 48, 120

Default value used if empty, missing or bad value: 24 month",
   "media": "Media id to use for this project"
}

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
200: OK
404: Not Found
400: Client Error
422: Unprocessable Entity
403: Forbidden

Headers

Header	Value
Content-Type	application/vnd.hv-publish.v1+json application/hal+json application/json
Allow	Comma-separated list of all HTTP methods allowed

Body

{
    "id": "",
    "created": "",
    "author": "",
    "updated": "",
    "updator": "",
    "level": "",
    "state": "",
    "name": "The publication's name.",
    "hv_save": "The "HVSave" entity's id used to create the publication. If an "HVProject" entity's id is provided, this field isn't required: in this case, the last project's save is used.",
    "hv_project": "The "HVProject" entity's id used to create the publication. If a "HVSave" entity's id is provided this field isn't required.",
    "durability": "Time in month until the publication expires. Available duration are:\r\n2, 6, 12, 24, 48, 120 months.\r\n\r\nDefault value used if empty, missing or bad value: 24 month",
    "media": "The project's "Media" id. The Media's id of the video on top of which the interactivity is created.",
    "description": "Description from entry",
    "_links": {
        "self": {
            "href": "/hv-publish[/:hv_publish_id]"
        }
    }
}

DELETE /hv-publish[/:hv_publish_id]

Deletes the entity with the given id. Note that on success, the returned http status is "204, Entity has been deleted".

Request

EndPoint

https://services.adways.com/hv-publish[/:hv_publish_id]

Headers

Header	Value
Accept	application/vnd.hv-publish.v1+json application/hal+json application/json

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
204: No Content
404: Not Found
403: Forbidden

Headers

Header	Value
Content-Type	application/vnd.hv-publish.v1+json application/hal+json application/json
Allow	Comma-separated list of all HTTP methods allowed

HVLoadPublication

Returns a "HVPusblish" entity as a JSON. This is the data under the format the final user experience script is able to load.

Fields

Field	Description	Required
hv_publish_key	The publication's id to load.	YES
callback_name	The method's name to call with the request response as its parameter. Use it to perform a JSONP like process.	NO

GET /load-publication[/:hv_publish_key][/:password]

Request

EndPoint

https://services.adways.com/load-publication[/:hv_publish_key][/:password]

Headers

Header	Value
Accept	application/vnd.hv-publish.v1+json application/json application/*+json application/javascript

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
200: OK
404: Not Found
403: Forbidden

Headers

Header	Value
Content-Type	application/vnd.hv-publish.v1+json application/json application/*+json application/javascript
Allow	Comma-separated list of all HTTP methods allowed

Body

callback_name(
    {
        "loaded": true,
        "data":
            {
                "8": "2.0.001",
                "internalID": "8a584f06-7291-4cfe-8fb6-54178e4c5a09",
            etc...
            }
    });
or

    {
        "loaded": true,
        "data":
            {
                "8": "2.0.001",
                "internalID": "8a584f06-7291-4cfe-8fb6-54178e4c5a09",
            etc...
            }
    }

GetAnalytics

GetAnalytics request is securised and needs authentification. Users who want to retrieve analytics on an HVPublish entity must get an access to this entity. This POST get 3 parameters. Only 1 is required: hv_publish_id; the publication id.

Fields

Field	Description	Required
hv_publish_id	HVPublish entity's id to get analytics.	YES
start		NO
end	End date when to retrieve analytics. If not specified it's until now.	NO

POST /get-analytics

Request

EndPoint

https://services.adways.com/get-analytics

Headers

Header	Value
Accept	application/vnd.hv-publish.v1+json application/json application/*+json
Content-Type	application/vnd.hv-publish.v1+json application/json

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
201: Created
404: Not Found
400: Client Error
422: Unprocessable Entity
403: Forbidden

Headers

Header	Value
Content-Type	application/vnd.hv-publish.v1+json application/json application/*+json
Allow	Comma-separated list of all HTTP methods allowed

Body

{
	"publication": {...}, // Contains the publication entity
	"metrics": { // Contains all saved metrics for given project
		"enrichments":[ // Contain the list of hotspots for this publication and data associated.
			{
				"name":"hotspot #1", // Enrichment name, given within the studio
				"id":"ad2daf4a-ed9f-4c57-a808-f4b6ef595e22", // Adways enrichment id, never change during the enrichment life cycle
				"display":5, // Count of times the enrichment has been displayed to viewers
				"click":3 // Count of times the enrichment has been clicked by viewers
			},{ // Another node for another hotspot
				"name":"hotspot #2",
				"id":"a09b2820-972a-4da7-a6fc-11a997f81642",
				"display":2,
				"click":1
			}, ...
		],
		"enrichmentsEvents":[ // Contain the list of hotspots for this publication and data associated
			{
				"name":"hotspot #1", // Enrichment name, given within the studio
				"id":"ad2daf4a-ed9f-4c57-a808-f4b6ef595e22", // Adways enrichment id, never change during the enrichment life cycle
				"layer": { // Contains informations about the layer containing the enrichment
					"id": 1, // Adways layer's id
					"name": "HOTSPOT" // Layer's name: POPUP|HOTSPOT|CONTROLLER|WIDGET
				}, // Count of times the enrichment has been displayed to viewers
				"events": [ // Contain the list of events sent by this enrichment
					{
						"event_name": "enrichmentClick", // Event name sent by the enrichment
						"custom_event": 0, // Boolean, 0 if event sent by adways engine, 1 if event sent by the template's developper
						"hits": 5151 // Nombre of hits for this event
					},
					{
						"event_name": "enrichmentDisplay",
						"custom_event": 0,
						"hits": 7840
					}
				]
			},{ // Another node for another popup
				"name":"popup #1",
				"id":"a09b2820-972a-4da7-a6fc-11a997f81642",
				"layer": {
					"id": 4,
					"name": "POPUP"
				},
				"events": [
					{
						"event_name": "CloseClicked",
						"custom_event": 1,
						"hits": 2561
					}
				]
			}, ...
		],
		"percentConsumed": { // This node allowed user to know how many viewers watch the video at a given percent 
			"0": { // Key here is the percent of the full video. So viewers at 0% means, viewers at the time 0
				"total":3, // Total viewers at that moment
				"interactive":3, // Number of viewers at that moment watching the video with interactions
				"noninteractive":0 // Number of viewers at that moment watching the video without interactions (on iphone, ie6, or others...)
			},
			"10": { // New node at 10% of the full video.
				"total":3,
				"interactive":3,
				"noninteractive":0
			},
			"20": {
				"total":3,
				"interactive":3,
				"noninteractive":0
			},
			"30": {
				"total":2,
				"interactive":2,
				"noninteractive":0
			},
			"40": {
				"total":1,
				"interactive":1,
				"noninteractive":0
			},
			"50": {
				"total":1,
				"interactive":1,
				"noninteractive":0
			},
			"60": {
				"total":1,
				"interactive":1,
				"noninteractive":0
			},
			"70": {
				"total":1,
				"interactive":1,
				"noninteractive":0
			},
			"80": {
				"total":1,
				"interactive":1,
				"noninteractive":0
			},
			"90": {
				"total":1,
				"interactive":1,
				"noninteractive":0
			},
			"100": {
				"total":1,
				"interactive":1,
				"noninteractive":0
			}
		},
		"states": { // Contains informations about the global state of the video.
			"load": { // Load allow user to know how many times the publication has been loaded.
				"total":4,
				"interactive":4,
				"noninteractive":0
			},
			"start": { // Start means, how many times the video starts really. When using autoplay on video Start is near to load count.
				"total":3,
				"interactive":3,
				"noninteractive":0
			},
			"complete": { // Number of viewers who whatch the end of the video. It is the video complete count
				"total":0,
				"interactive":0,
				"noninteractive":0
			}
		}
	}
}

Home / Documentation

HVPublish (v1)

HVPublish

Fields

GET /hv-publish

Request

EndPoint

Headers

Response

Status Codes

Headers

Body

POST /hv-publish

Request

EndPoint

Headers

Body

Response

Status Codes

Headers

Body

GET /hv-publish[/:hv_publish_id]

Request

EndPoint

Headers

Response

Status Codes

Headers

Body

PATCH /hv-publish[/:hv_publish_id]

Request

EndPoint

Headers

Body

Response

Status Codes

Headers

Body

PUT /hv-publish[/:hv_publish_id]

Request

EndPoint

Headers

Body

Response

Status Codes

Headers

Body

DELETE /hv-publish[/:hv_publish_id]

Request

EndPoint

Headers

Response

Status Codes

Headers

HVLoadPublication

Fields

GET /load-publication[/:hv_publish_key][/:password]

Request

EndPoint

Headers

Response

Status Codes

Headers

Body

GetAnalytics

Fields

POST /get-analytics

Request

EndPoint

Headers

Response

Status Codes

Headers

Body