Asset JSON format¶
Current format version: 1.4.2
Legend
| Importance | Description |
|---|---|
| mand | mandatory |
| rec | recommended |
| opt | optional |
| edt | of interest only for editing purposes, not for display |
| depmand | mandatory depending on the value of another property |
The asset description separates the properties, which are typically a short json snippet, from the larger resources required for rendering (images, 3d model) and for its mission (video, audio...). The container associating the two sections also holds administrative properties (creator, dates...) and location information (document/page).
Note
The reference implementation is in the code for the editor, and in particular the source file Aura.ts defining the format of the data type.
1. container¶
| Tag | Type | Importance | Description |
|---|---|---|---|
| aura | aura section | mand | properties of the asset. See below for details |
| files | files section | depmand | resources for the asset. See below for details |
| id | string | rec | auto generated id |
| inserted | date string | edt | creation timestamp, in ISO 8601 date representation |
| updated | date string | edt | last modification timestamp, in ISO 8601 date representation |
| username | string | edt | last modification author |
| page | number | rec | page where the asset is located, starting from 0 |
2. 'aura' section ¶
Describes the properties of the asset.
| Tag | Type | Importance | Description |
|---|---|---|---|
| api | string | rec | protocol version, 2.6->...->2.6.9->2.6.a to follow the alphabetical order |
| id | string | rec | auto generated id |
| name | string | rec | human-friendly label |
| center_x | number | mand | center on x axis, in % of marker width |
| center_y | number | mand | center on y axis, in % of marker height, 100% being bottom |
| center_z | number | opt | center on z axis (vertical if the document was flat on a table), in % of marker height, 0 being the plane of the document, >0 being up |
| order | number | depmand | order in which the assets are displayed/interpreted in the scene In the most common case, it's the Z-order background to front, so the highest is on top. It is also the order in which non-visible assets may be interpreted, the order in which they may receive messages etc... Mandatory if more than one asset. Unpredictable result if missing or equal values. |
| rect | [number, number] | mand | for rectangular assets, [witdh , height], in % of width and height, centered on above center_x/center_y |
| rect_fixed_ratio | boolean | edt | whether the ratio of width/height should be kept when editing |
| angles | {angles} | opt | angles for 3d representations |
| inactive | boolean | edt | if true, the augmentation should not be rendered |
| immutable | boolean | edt | client system cannot delete or change the asset |
| background | {resource name} | opt | reference to the resource image used as icon. Will cover the whole surface defined by rect. |
| model3d | {3d model} | opt | properties for using a 3d model as visual for the asset. Can coexist with a background icon. The dimensions are controlled by the scaling. See below for details |
| actions | [{action},...] | opt | interactions for this asset |
| generators | [{generator},...] | edt | an array of generated content definitions. See below for details. May be skipped when the aura is not sent in an edition context (ie: for display only). |
2.1 Angles definition ¶
At the moment only one set of angles is defined: marker, indicating how to position the asset with respect to the marker.
Convention for the signs of angles is to use a right-handed coordinate system.
| Tag | Type | Importance | Description |
|---|---|---|---|
| alpha | number | opt | x-axis rotation, in degrees |
| theta | number | opt | y-axis rotation, in degrees |
| psi | number | opt | z-axis rotation, in degrees |
2.2 3d model definition ¶
| Tag | Type | Importance | Description |
|---|---|---|---|
| data | string | mand | reference to a resource containing the 3d model |
| scale | {x: number, y: number, z: number} | opt | scaling to apply to the 3d model, based on the scale_unit (default: 1 in every direction). |
| scale_unit | number | rec | base unit for the 3d model: how many 3d units in the document height. Default is 1, which means a 1x1x1 3d cube with no scaling will have exactly the document height. |
2.3 Action definition ¶
| Tag | Type | Importance | Description |
|---|---|---|---|
| event | string | opt | Defines when the action is fired. See below. Default if not included: 'click' |
| type | string | mand | Defines the type of data which drives the action to trigger: 'url', 'email', 'phone', 'agenda', 'download', 'contact', 'audio', 'video', 'text', 'html', 'share', 'analytics', 'controller' |
| data | string or object | mand | The data that will be used when the action is triggered, in accordance with the action type. In general, data is an object, but when it contains only one property, it can be replaced by the value of that property. See details below. |
| options | string | opt | Object describing extra type-specific options. Currently: for videos, |
| target | string | opt | Where the action should happen. See below. |
2.3.1 Action events:¶
| Event name | Description |
|---|---|
| undefined | click |
| 'click' | click |
| 'page_open' | autoplay of audio/video at page display |
| 'message' | on reception of a message sent by another aura (projected) |
2.3.2 Action types and data:¶
| Action type | Data format | Description |
|---|---|---|
| 'phone' | string | phone number as a free string |
| 'email' | string | email address as a free string |
| 'url' | string | url as a free string |
| 'agenda' | string | specially formatted url of link to calendar entry |
| 'download' | string | resource name of a file to download |
| 'contact' | string | resource name of a vcard file |
| 'audio' | string | resource name of an audio file |
| 'video' | string | resource name of a video file |
| 'html' | string | resource name of a webview html file |
| 'html' | object | For templated webviews, an object describing the source properties and the resulting html. See below. |
| 'share' | share object | Object with the useful properties covering a Android share intent, a Facebook share, and the iOs equivalent. See below. |
| 'analytics' | string | Analytics id, for instance for GA: "UA-XXXX-N" |
| 'controller' | tba | tba |
2.3.2.1 Templated webview action definition:¶
| Tag | Type | Importance | Description |
|---|---|---|---|
| template_name | string | mand | Name of the template. Has to be known by the editing software. At the moment, the only one supported: "slider2d" |
| template_parameters | object | edt | template-dependent custom object |
| resource | string | mand | resource name of the resulting html file |
2.3.2.2 Share action definition:¶
| Tag | Type | Importance | Description |
|---|---|---|---|
| url | string | opt | url to share |
| title | string | opt | title, for the services which accept a title for shared content |
| description | string | opt | description, for the services which accept a description for shared content |
| file | string | opt | resource name of the shared content |
2.3.3 Action targets:¶
| Target name | Description |
|---|---|
| '_blank' | a new browser window |
| 'window' | full screen video , modal webview |
2.4 Generator definition ¶
A generator definition includes the name of the generating tool, the reference to the generated resource, and the reference to the resource containing the source/parameters/description.
For editing purposes only: all generation must be completed by the editing tool and a generated version of the resources available for aura representation (on-the-fly generation of the artifact resources by the player is not supported).
Example: using "tinymce" for text exported as images.
| Tag | Type | Importance | Description |
|---|---|---|---|
| resource | string | mand | reference to the generated resource (artifact) |
| generator | string | mand | name of the tool converting the source into the artifact. Should be known by the edition tool, which can then invoke it or inform the operator. Example: "tinymce" |
| source | string | mand | reference to the input resource (source code or parameters) which the generator can generate the artifact from. Example: the html-like native tinymce format. |
3. 'files' section ¶
Describes the resources used by the asset as a map where the keys are the resource names (referenced by properties of the asset) and the values are the resource descriptors.
The resources can be embedded (in base64) or online (url).
| Tag | Type | Importance | Description |
|---|---|---|---|
| filename | string | rec | filename, for instance when downloading and saving the file |
| mimetype | string | mand | canonical mime type of the resource |
| filesize | number | rec | size of the file |
| base64 | string | depmand | (at least base64 or url must be present) base64 representation of the file content |
| url | string | depmand | (at least base64 or url must be present) URL to retrieve the file content |