Documentation and examples of the INSM Template API

An Instoremedia template is an zip file containing files to render dynamic content on a screen. The zip file must contain a descriptor file called start.xml. A template may currently be implemented using HTML/JS or .NET/C#

A templates main purpose it to render content. But the API provides many additional features for configuration and integration.

Template configuration is provided as the TemplateDataSet. The available data fields are decalred statically in start.xml. When uploading and schduling the template on the AMS the configuration is defined, stored on the server, transferred to players and stored locally on the player. Everytime a new dataset arrives to a player the template will receive the TemplateDataSetChanged event.

Read-only platform attributes are available as key/values and will describe the runtime environment. E.g. the current channel, region, opening hours etc.

A template may generate and store data as key/values using TemplateProperties. This data is stored on the player to be used when a player restart. Properties can be defined to be shared accross multiple running instances of templates. All properties is also sent the the AMS when changed. If the property values are numeric, they will also be aggregated into statistics. The time segements for statistical data is defined by a configuration on the AMS.

Advanced statistics may be generated using the Statistics wrapper class. This may be used to measure both count and duration of generic actions by calling an API on begin and end.

A template can record playback of individual files or datasets (assets). Multiple instances of the same file can be announced and are individually tracked. This is used for proof of play logging.

A plugin is a local running component. It works much the same way as a template but does not render anything and cannot be scheduled at times. It is used for separating integration and presentation. Normally plugins are used for integration with hardware. A plugin has a name and only on instance is allowed per plugin name.

A template may connect to a plugin to send, receive of be notified by the plugin of data as key/Values.

Commands are fast volatile in memory commands sent from the AMS to players. Commands are intended to be used for temporary modifications on a template. If persistent change is desired the configuration should instead be changed using the content dataset.

A command is a key/value pair that might return replay as a string or byte array.

Communication between templates locally or between players is done using warpspace. Each warpspace has a unique name and are isolated from each other. Currently a warpspace involving multiple players must be configured with a master IP address of one of the players but it does not matter which one. Any player can send a message to any other player, or broadcast to all players. The call can be synchronous or asynchronous. The call can have a reply if sent to a single peer. Broadcast messages cannot be replied.

In most cases a template preview will be automatically generated from a headless preview player. But in some cases this will not be possible. In that case there are other options to avoid a black frame and display a relevant preview image.

Configure one input file to be full screen preview.

Embed an image called Preview.jpg to display a static preview image.

An Instoremedia template must contain a start.xml file. The start.xml file has three parts:

• Manifest - Standard meta data about this file (template or plugin)
• Template - Standard meta data about the template
• Content - Custom defined meta data about the dynamic parameters the template expect from a user

This dataset contains defined information about the file. Only defined item ids are permitted.

Title - Title of the template.

DisplayName - Display fiendly name of the template.

Description - Description of the template.

Category - Value is the category title.

Version - Version of the template.

Type - Type should be "Template" for templates.

Vendor - Vendor of the template.

StartFile - Start file of the template.

FileType - File Type of the template.

FileHandler - FileHandler of the template.

This dataset contains defined information about the template. Only defined item ids are permitted.

Orientation - Value can be “Landscape” or “Portrait”

Resolution - Value is pixels [width]x[height] e.g. “1920x1080”

Identity - Identifier e.g. "Image" or "Movie". If specified templates with the same identity will be considered to have the same function. This is used as the TemplateName in the playlist data. If it is not present the manifest Title will be used instead. This may be used as an icon hint to override icons.

UrlItem - Value is the content dataset item id with an url from which the template should be loaded.

Transition - Default transition effect like "Fade".

IsTransitionsEnabled - Transitions enabled or not.

Duration - Duration value of transition.

IsDurationEnabled - Duration enabled or not.

AutoDuration - Auto duration is enabled or not.

IsAutoDurationOptionEnabled - Auto duration option enabled or not.

IsVolumeControlEnabled - Volume control enabled or not.

IsActiveXHost - Active XHost is enabled or not.

This dataset contains user defined configuration options for the template. The item Ids user defined but only defined attributes are permitted.

Type of parameter

    Text        - Text string
    Numeric     - Number
    Boolean     - True/False
    MediaFile   - File reference
    Image       - File reference restricted to images
    Audio       - File reference restricted to audio
    Movie       - File reference restricted to movie
    Archive     - File reference restricted to zip
    Url         - Web link
    Html        - HTML text

Visual type of parameter

   text         - Text field
   checkbox     - True/False option
   dropdown     - Option list (requires AvailableValues)
   browse       - Select a file
   slider		- For numeric values
   colorpicker  - Choose a color
   playlist		- Choose a sub playlist
   extendedtext - Rich text field
   datagrid     - Display a table

DisplayName - Name of parameter to be displayd to the user

DisplayGroupName - Name of visual grouping of items

DisplayGroupId - Id of visual grouping of items (integer)

Required - True if this attribute is required from the user

RequiredMessage - Messages displayed if the user did not specify a value

AvailableValues - Options for VisualType dropdown

FilePattern - File extension options for VisualType browse

Advanced - True if parameter is an advanced parameter

Hidden - True if the parameter is hidden from the user

IsPreviewEnabled - True if automatic preview rendering should be attemted. If this is False and IsPreviewItemEnabled is also false the template can embedd a static file called Preview.jpg as the preview image.

IsPreviewItemEnabled - True if an item should be used as preview for the whole template. In this case PreviewItem must be defined

PreviewItem - Key of dataset item id to use as preview. This must be a file.

Color - Color as hex value with A,R,G and B.

FileDescription - Kind of file with file extensions.

Rows - Number of rows.

Font - Name of the font.

FontBold - Bold font is enabled or not.

FontItalic - FontItalic is true or false.

FontSize - Selected size of the font.

TextAlign - Alignment of text left or right.

AllowEdit - Allow edit true or false.

Fonts - All fonts options.

FontSizes - All font size options.

DropShadow - enabled or not.

DataColumnDisplayName.1 - datagrid column display name.

DataColumnKey.1 - datagrid column display key.

DataColumnRequired.1 - datagrid column required or not.

DataColumnRequiredMessage.1 - datagrid column required message.