Aura Format Specification

1. Introduction

This document describes the "aura" format used by various ARGO systems and products to define document and AR augmentations.

In particular, it is used by ARGOFlow's API and for embedded assets in Augmented PDF files.

Note:

There are two variants of the format: - one with "snake_case" underscore-separated property names (ie: long_property_name) - the other with JSON-style "camelCase" property names (ie: longPropertyName).

Typically, the API uses the "snake_case", whereas Javascript code will use "camelCase".

Conversion should be straightforward.

This document describes the JSON "camelCase" version, from the point of view of the ARGOFlow reader. Other systems may use extra properties not described in this document, or require properties described as optional here.

2. Specification

version 2.0.1

'aura' object

property	type	importance	description
api	string	mandatory	version of the aura format
id	string	mandatory	system id
name	string	mandatory	human-friendly label
active	boolean	mandatory	inactive auras are ignored by the rendered
hidden	boolean	optional	hidden auras are not normally displayed, but can still be controlled programmatically
showInResponsiveViews	responsiveness	optional	mobile/destop...; if not defined: displayed in every context
order	number	optional	rendering order; if not defined, the order the auras are parsed will be used
dimensions	dimensions	mandatory
coordinates	coordinates	mandatory
angles	angles	optional
background	string	optional	name of resource containing the image to display for 2d rectangular augmentations
model3d	3d model	optional	name of resource containing the 3d model for 3d augmentations
actions	[array of action]	optional
resources	[array of resource]	optional	array of resources referenced by other properties

'dimensions' object

property	type	importance	description
width	number	mandatory
height	number	mandatory

'coordinates' object

property	type	importance	description
x	number	mandatory
y	number	mandatory
z	number	optional

'angles' object

property	type	importance	description
alpha	number	optional
theta	number	optional
psi	number	optional

'responsiveness' object

property	type	importance	description
desktop	boolean	mandatory	augmentation visible in desktop environment
mobile	boolean	mandatory	augmentation visible in mobile environment

If the object exists, all known environments should have a value. To ensure backward compatibility for future environments, environments not defined can be assumed as having a true value.

'3d model' object

property	type	importance	description
data	string	mandatory	name of resource containing the 3d model
scale	3d scaling	optional
scaleUnit	number	optional
options	3d options	optional

'3d scaling' object

property	type	importance	description
x	number	optional
y	number	optional
z	number	optional

Missing values are assumed to be 1 (no scaling along that axis)

'3d options' object

property	type	importance	description
loop	boolean	optional	if the 3d model contains animations, whether to loop when playing them

'resource' object

property	type	importance	description
name	string	mandatory	name of the resources, used to reference it in other properties
filename	string	optional
mimetype	string	optional
filesize	number	optional
url	string	optional
base64	string	optional

url and base64 are exclusive, and one must always be defined.

'action' object

All action share common properties, some depend on the action type.

property	type	importance	description
type	action type	mandatory	name of the resources, used to reference it in other properties
event	action event	optional	default value is "click"
target	action target	optional
data	action data	optional	type-dependent
options	action options	optional	type-dependent

'action type' object

A string with one of the following values:

value
"phone"
"email"
"url"
"image"
"audio"
"video"
"text"
"html"
"share"
"analytics"
"controller"
"download"
"contact"
"agenda"

'action event' object

A string with one of the following values:

value
"click"
"page_open",

'action target' object

A string with one of the following values:

value
"window"
"self"

'action data' object

When data is to be defined, it is enclosed in a simple wrapper:

property	type	importance	description
type	action data type	mandatory	action type dependent, as indicated in the action data value table
value	action data value	mandatory	action type dependent

'action data type' object

A string with one of the following values:

value
"resource"
"url"
"base64"
"value"

'action data value' object

The nature of the data value depends on the action type as follows:

action type	data type	value type	importance	description
"phone"	"url"	string	mandatory	phone uri
"email"	"url"	string	mandatory	email uri
"url"	"url"	string	mandatory	destination url
"image"	n/a
"audio"	"resource"	string	mandatory	name of the resource defining an audio file
"video"	"resource"	string	mandatory	name of the resource defining a video file
"text"	n/a
"html"	"resource" or "value"	string or html action data	mandatory	name of the resource defining the webview contents, or templated webview definition
"share"	"value"	share action data	mandatory
"analytics"	"value"	string	mandatory	analytics id
"controller"	"resource"	string	mandatory	name of the resource defining the controller webview contents
"download"	"resource"	string	mandatory	name of the resource defining the content to download
"contact"	"resource"	string	mandatory	name of the resource defining a vcard file
"agenda"	"url"	string	mandatory	url of the agenda entry at the calendar service site

'share action data' object

property	type	importance	description
url	string	optional
title	string	optional
description	string	optional
file	string	optional

Note: in some cases, a string containing the serialize version of the object has been used.

'html action data' object

property	type	importance	description
resource	string	mandatory	name of the resource defining the content of the webview
template_name	string	optional	not normally used for rendering
template_parameters	object	optional	not normally used for rendering

'action options' object

The nature of the options depends on the action type as follows:

action type	data type	importance	description
"phone"	n/a
"email"	n/a
"url"	n/a
"image"	n/a
"audio"	audio action options	optional
"video"	video action options	optional
"text"	n/a
"html"	n/a
"share"	n/a
"analytics"	n/a
"controller"	n/a
"download"	n/a
"contact"	n/a
"agenda"	n/a

'audio action options' object

property	type	importance	description
loop	boolean	optional

'video action options' object

property	type	importance	description
loop	boolean	optional
alpha_channel	boolean	optional
transparency_color	string	optional