How to create an embed code via API

How to create an embed code via API

Introduction


Through THRON APIs you can manually create embed codes to deliver one or more content within a specific project using a specific template (a template is a layout customization for the player itself). More specifically, in this article we will make a distinction between a single content embed (one-time), for which it is sufficient to build the entire embed code after creating or retrieving the template to be used, and multiple or recursive embed, in case you have to include all the content from a specific folder within a project. In this second case you will have to use a THRON Custom Application Manager application.

 

One-time embed code

The first thing to do when embedding a content is to decide which layout to be used for the specific sharing. A layout is identified into THRON Platform by a template, which is a combination of look (css) and behavior (js).

Retrieve an existing template

If a template has already been created you can retrieve its ID by invoking a playerembedtemplate/list request. It is a POST request which can be invoked by template managers or by users with the permission to manage company details and appearence or to access the template center.

The URL of the request is structured as follows:

//[clientId]-view.thron.com/api/xcontents/resources/playerembedtemplate/list/[clientId]

Among the headers you will have to include the user's token; in the body you can paste the following JSON:

{
    "criteria": {
        "text": "<Place here the name of the template you are looking for, otherwise omit this parameter>",
        "removed": false
    },
    "options": {
        "returnRoles": false,
        "returnValues": true
    }
}

In the response you will get the list of all the available templates, or the specific template if you have provided the name in the "text" parameter; take note of the ID of the template you wish to use for the specific content sharing.

 

Create an embedCodeId

Once you have retrieved the specific template to be used for the specifc embed, you have to create an embedCodeId; by doing this you will obtain a pkey which will allow you to embed the content by using the specifc template.

The embedCodeId can be created by invoking the web service playerembedcode/insert/. It is a POST request which has to be invoked by users with the right to share the specific content.

The URL of the request is structured as follows:

//[clientId]-view.thron.com/api/xcontents/resources/playerembedcode/insert/[clientId]

In the body of the request you can paste the following JSON, filling required parameters:

{
    "source": {
        "id": "<xcontentId or prettyId here>",
        "entityType": "CONTENT"
    },
    "value": {
        "name": "<Enter a name for the embed here>",
        "template": {
            "templateId": "<Paste the id of the template to be used>",
            "templateType": "CUSTOM"
        },
        "embedTarget": "GENERIC",
        "values": [{
            "name": "width",
            "value": "<Enter width here>"
        }, {
            "name": "height",
            "value": "<Enter height here>"
        }, {
            "name": "embedType",
            "value": "DEFAULT"
        }],
        "enabled": true
    }
}

Where:

  • id: (string, mandatory), it is the identifier of the content to be embedded, you can either use its xcontentId or prettyId.
  • name: (string, mandatory), it is the label for the specific embed you are about to create. 
  • templateId(string, mandatory) the id of the template to be used in this specific embed.
  • values: (object, mandatory, CE1 only) a list of parameters to be used by the player when delivering the content; each parameter requires a couple of strings: name which is the actual name of the parameter and value for the desired value. Available parameters are:
    • autoplay
    • loop
    • zoom
    • noskin
    • displaylinked
    • displaydownload
    • muted

All Player parameters are documented here, as well as Events and APIs.

When embedding an image you can decide to perform a specifc crop with Real Time Image Editor (the application must be active on your THRON Platform). If this is the case you will have to include in the body a specific object: rtieValues which provides the parameters of the crop. Each parameter requires a couple of strings: name which is the actual name of the parameter and value for the desired value. Available parameters are:

  • scalemode
  • cropx
  • cropy
  • cropw
  • croph
  • adjustcrop
  • fill
  • fillcolor
  • enhance
  • format

For a complete description of RTIE parameters, please refer to this article. A sample JSON including RTIE values is provided below:

{
    "source": {
        "id": "<xcontentId or prettyId here>",
        "entityType": "CONTENT"
    },
    "value": {
        "name": "<Name for the embed here>",
        "template": {
            "templateId": "<Id of the template to be used here>",
            "templateType": "CUSTOM"
        },
        "embedTarget": "GENERIC",
        "values": [{
            "name": "width",
            "value": "<width here>"
        }, {
            "name": "height",
            "value": "<height here>"
        }, {
            "name": "embedType",
            "value": "DEFAULT"
        }],
        "rtieValues": [{
            "name": "<rtie param name here>",
            "value": "<rtie param value here>"
        }],
        "enabled": true
    }
}

In the response of the request you will obtain a pkey which can be used to embed THRON Player.

 

Embed THRON Player

Now that you have a valid pkey which is related to a specific template, you can embed THRON Player using the following form:

var options = {
        clientId: "<your clientId here>",
        xcontentId: "<xcontentId here>",
        sessId: "<the pkey here, alternatively you can provide a valid user token>",
        autoplay: false,
        muted: false
    };
var player = THRONContentExperience("<ID of the div where the embed must be displayed>", options);

All the available parameters of the embed code are illustrated here.

 

Multiple embeds

In case you have to recursively embed all the content in a specific folder, the right approach is to use a THRON Custom Application Manager

This application can be installed on a THRON folder hence gaining access to all the content therein published. Through the Management of this application you can create a pkey which can be used to embed any of the content within the folder. To do so, refer to the "Create new sharing" section, and click on the "Add sharing button".

 

Schermata_2017-06-07_alle_14.52.43.png

This procedure will trigger the creation of an embed script which can be copied and paste into any project, you can make two choices:

  1. Create a Public Sharing: A pkey will be generated that will allow access to all the content within the folder without restriction, the embed made with this pkey will be public and the content will be indexed by search engines.
  2. Create a Secure Sharin: The content will be delivered only if a valid user token is provided. It ensures the privacy of the content which will not be indexed by search engines.

 

 

Schermata_2017-06-07_alle_14.56.32.png

 

Select the Template to be used by the specific embed and click on "Confirm".

In the following example we have created a Public Sharing, subject to a pkey which is visible both in the upper part of the modal and within the script under the "sessId" parameter. The only dynamic part of the provided script is the "xcontentId" which can be filled with the id of the specific content to be embedded (must be a content of the folder).

 

 

Schermata_2017-06-07_alle_14.57.09.png

 

The validity of the pkey can be controlled with just one click by using the checkbox in the Management of the application, if turned off, all the embeds will no longer be available on your channels.

 

Schermata_2017-06-07_alle_15.04.16.png

 

Embed THRON Player

Now that you have a valid pkey which is related to a specific template, you can embed THRON Player using the following form:

var options = {
        clientId: "<your clientId here>",
        xcontentId: "<xcontentId here>",
        sessId: "<the pkey here, alternatively you can provide a valid user token>",
        autoplay: false,
        muted: false
    };
var player = THRONContentExperience("<ID of the div where the embed must be displayed>", options);

All the available parameters of the embed code are illustrated here.

Was this article helpful?
0 out of 0 found this helpful

Have more questions?

SUBMIT A REQUEST

Hai altre domande?

INOLTRA UNA RICHIESTA

Comments