ARML Specification for Wikitude

Developer Specification for ARML Support of Wikitude World Browser.

Authors:
Martin Lechner, CTO, Wikitude GmbH

Introduction

ARML (augmented reality markup language) is a specification that allows content developers create content that is displayed on various mobile AR browsers. Wikitude is the first browser that natively supports ARML. ARML is built on a subset of KML, a set of common tags supported across all browsers and some browser (e.g. Wikitude) specific extensions. This specification describes the full set of tags supported by Wikitude.

The ARML document must be a valid XML in UTF-8 encoding. The text of the tags may be enclosed by a CDATA section to prevent un-escaped characters like <, >, ...

Wikitude ARML Example

When you create an ARML for Wikitude you can use the example below as a starting point.

wikitude-arml.xml:

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2"
     xmlns:ar="http://www.openarml.org/arml/1.0"
     xmlns:wikitude="http://www.openarml.org/wikitude/1.0">

    <Document>
        <ar:provider id="mountain-tours-I-love.com">
            <ar:name>Mountain Tours I Love</ar:name>
            <ar:description>My preferred mountain tours in the alps. Summer and Winter.</ar:description>
            <wikitude:providerUrl>http://www.providerhomepage.com </wikitude:providerUrl>
            <wikitude:tags>travel, hiking, skiing, mountains</wikitude:tags>
            <wikitude:logo>http://www.mountain-tours-I-love.com/wikitude-logo.png </wikitude:logo>
            <wikitude:icon>http://www.mountain-tours-I-love.com/wikitude-icon.png </wikitude:icon>
            <wikitude:shortName>Mountain Tours</wikitude:shortName>
            <wikitude:promotionText>Join us for the pick of your dreams!</wikitude:promotionText>
            <wikitude:promotionGraphic>http://www.somesite.com/promotionGraphic.png </wikitude:promotionGraphic>
            <wikitude:hiResIcon>http://www.mountain-tours-I-love.com/hi_res_image.png </wikitude:hiResIcon>
            <wikitude:featureGraphic>http://www.somesite.com/featureGraphic.png </wikitude:featureGraphic>
            <wikitude:noPromotion>true</wikitude:noPromotion>
        </ar:provider>
        <Placemark id="123">
            <ar:provider>mountain-tours-I-love.com</ar:provider>
            <name>Gaisberg</name>
            <description>Gaisberg is a mountain to the east of Salzburg, Austria</description>
            <wikitude:info>
                <wikitude:thumbnail>
                	http://www.mountain-tours-I-love.com/gaisberg-thumb.png 
                </wikitude:thumbnail>
                <wikitude:hiResImageUrl>
                	http://www.mountain-tours-I-love.com/hi_image_resolution.png 
                </wikitude:hiResImageUrl>
                <wikitude:phone>555-9943</wikitude:phone>
                <wikitude:url name="Read from Wikipedia">http://en.wikipedia.org/wiki/Gaisberg </wikitude:url>
                <wikitude:email>info@mountain-tours-I-love.com</wikitude:email>
                <wikitude:address>Jakob-Haringer-Str. 5a, 5020 Salzburg, Austria</wikitude:address>
            	 <wikitude:attachments>
               	 	<wikitude:attachment name="Gaisberg Map">
               	 		<wikitude:attachment-url>http://www.mountain-tours-I-love.com/gaisberg-map-to-print.pdf </wikitude:attachment-url> 
               	 	</wikitude:attachment>
               	 	<wikitude:attachment name="Hillclimb Race"> 
               	 		<wikitude:attachment-thumbnail>http://www.a-site.com/thumb-file.png </wikitude:attachment-thumbnail>
               	 		<wikitude:attachment-url>http://www.mountain-tours-I-love.com/gaisberg-hillclimb-race-to-print.pdf </wikitude:attachment-url> 
               	 	</wikitude:attachment>
               	 </wikitude:attachments>
       		</wikitude:info>
            <Point>
                <coordinates>13.11,47.81,1158</coordinates>
            </Point>
        </Placemark>
        <Placemark id="534">
            <ar:provider>mountain-tours-I-love.com</ar:provider>
            <name>Untersberg</name>
            <description>The Untersberg is a mountain massif of the Berchtesgaden Alps, between Berchtesgaden, Germany and Salzburg, Austria.</description>
            <wikitude:info>
                <wikitude:thumbnail>http://www.mountain-tours-I-love.com/untersberg-thumb.png </wikitude:thumbnail>
                <wikitude:phone>555-9945</wikitude:phone>
                <wikitude:url name="Untersberg Wikipedia Article">http://en.wikipedia.org/wiki/Untersberg </wikitude:url>
                <wikitude:email>info@mountain-tours-I-love.com</wikitude:email>
                <wikitude:address>Jakob-Haringer-Str. 5a, 5020 Salzburg, Austria</wikitude:address>             
            </wikitude:info>            
            <wikitude:targets>
  				<wikitude:target name="CALL" group="1">
    				<wikitude:tExecution>
      					<wikitude:tUrl>http://www.myUrl1.com?param1=this&param2=%%IP%%</wikitude:tUrl>
      					<wikitude:tHeaders>
        					<wikitude:tHeader>
          						<wikitude:tHeaderKey>exec1header1Key</wikitude:tHeaderKey>
          						<wikitude:tHeaderValue>%%CLIENT_HASH%%</wikitude:tHeaderValue>
        					</wikitude:tHeader>
        					<wikitude:tHeader>
          						<wikitude:tHeaderKey>exec1header2Key</wikitude:tHeaderKey>
          						<wikitude:tHeaderValue>exec1header2Value</wikitude:tHeaderValue>
        					</wikitude:tHeader>
      					</wikitude:tHeaders>
    				</wikitude:tExecution>
    				<wikitude:tExecution>
      					<wikitude:tUrl>http://www.myUrl2.com?a=this&b=that</wikitude:tUrl>
    				</wikitude:tExecution>
  				</wikitude:target>
  				<wikitude:target name="ROUTE_TO" group="1">
    				<wikitude:tExecution>
      					<wikitude:tUrl>http://www.myUrl1.com?param1=this&param2=%%IP%%</wikitude:tUrl>
      					<wikitude:tHeaders>
        					<wikitude:tHeader>
          						<wikitude:tHeaderKey>exec1header1Key</wikitude:tHeaderKey>
          						<wikitude:tHeaderValue>%%CLIENT_HASH%%</wikitude:tHeaderValue>
        					</wikitude:tHeader>
        					<wikitude:tHeader>
          						<wikitude:tHeaderKey>exec1header2Key</wikitude:tHeaderKey>
          						<wikitude:tHeaderValue>exec1header2Value</wikitude:tHeaderValue>
        					</wikitude:tHeader>
      					</wikitude:tHeaders>
    				</wikitude:tExecution>
    				<wikitude:tExecution>
      					<wikitude:tUrl>http://www.myUrl2.com?a=this&b=that</wikitude:tUrl>
    				</wikitude:tExecution>
  				</wikitude:target>
			</wikitude:targets>
            <Point>
                <coordinates>12.62,47.52,1852</coordinates>
            </Point>
        </Placemark>
    </Document>
</kml>

Tags

kml (required)

Root tag as described by the KML standard. Additionally to the standard KML namespace you should add the ARML namespace and Wikitude specific namespaces.

Attributes

Name Required Description
xmlns no http://www.opengis.net/kml/2.2: Standard KML namespace
xmlns:ar no http://www.openarml.org/arml/1.0: Standard ARML namespace
xmlns:wikitude no http://www.openarml.org/wikitude/1.0: Public Wikitude namespace
xmlns:wikitudeInternal no http://www.openarml.org/wikitudeInternal/1.0: Internal Wikitude namespace for statistical information returned to the mobile client

ar:provider (required)

Identifies a content provider or content channel. Wikipedia, Youtube or Twitter are popular separate providers. Each provider must have an unique identifier.

You can add more than one provider, each provider will show up as a seperate entry in the provider list.

Attributes

Name Required Description
id yes Identifies the content provider or content channel. Must be unique across all providers

ar:name (required)

Name of the content provider. This name will be used to display the content provider in the settings and bookmarks menu of the browser.

ar:description (optional)

Description of a content provider that provides additional information about the content displayed.

wikitude:providerUrl (optional)

Link to the content provider. If the content provider adds an own logo the user will be redirected to the providerUrl when clicking on the logo.

wikitude:tags (optional)

Comma separated list of keywords that characterize the content provider. When users search for content in Wikitude the tags will be searched as well. A match in the tags is higher ranked than in the description.

wikitude:logo (optional)

Logo displayed on the left bottom corner on Wikitude when an icon is selected.

Format: 96x96 pixel, transparent PNG

wikitude:icon (required)

The icons are displayed in the cam view of Wikitude to indicate a point of interest (POI).

Format: 32x32 pixel, transparent PNG

wikitude:shortName (optional)

A short name for your World, should only be up to 20 characters, to be used when there's not enough space.

wikitude:promotionText (optional)

A promotion text describing your World in more details.

wikitude:promotionGraphic (optional)

A graphic advertising your World.

Format: 180x120 pixel, transparent PNG

wikitude:hiResIcon (optional)

A high resolution icon for your World which can be included in features.

Format: 512x512 pixel, transparent PNG

wikitude:featureGraphic (optional)

A graphic spotlighting your World in promotions.

Format: 1024x500 pixel, transparent PNG

wikitude:noPromotion (optional)

Opt-out from being promoted.

Placemark

Placemark describes one point of interest (POI) in Wikitude.

Attributes

Name Required Description
id yes Identifies a point of interest. Is used to update POIs when uploaded via Wikitude.me

ar:provider within Placemark (required)

Reference to the content provider definition.

name (required)

Name of the POI. Displayed as POI title.

description (optional)

Description of the POI. Currently no HTML formatting is allowed.

wikitude:info (optional)

Additional information about a POI that is displayed in the bubble.

wikitude:thumbnail (optional)

Specific POI image that is displayed in the bubble. This could be for instance a hotel picture for a hotel booking content provider.

Format: 64x64 pixel, PNG

wikitude:hiResImageUrl (optional)

Specific POI high resolution image that is displayed in the detail page. This could be for instance a crystal clear hotel picture for a hotel booking content provider.

Format: PNG

wikitude:phone (optional)

When a phone number is given, Wikitude displays a "call me" button in the bubble. You can directly call the person/organization behind the POI. E.g. call a restaurant to reserve a table for dinner.

wikitude:url (optional)

Link to a web page that contains additional information about the POI.

Attributes

Name Required Description
name no Used to display the name of the link

wikitude:email (optional)

Write the person/organization an email directly from Wikitude.

wikitude:address (optional)

Address of the POI. Also used to route to the location of the POI.

wikitude:attachments (optional)

Defines a section containing a list of attachments for the POI.

wikitude:attachment (option)

Defines an attachment for the POI. Mandatory when wikitude:attachments exists.

Attributes

Name Required Description
name no Used to display the name of an attachment link
type no Mime type of the attachment. If it is a known type it can automatically trigger an application start (e.g. audio/mpeg can start the attachment in the phones media player)

wikitude:attachment-url (optional)

Can be a link to a resource (image, PDF file, ...). You could use this to issue coupons or vouchers for potential clients that found you via Wikitude. Mandatory if wikitude:attachment exists.

wikitude:attachment-thumbnail (optional)

Used to display a thumbnail of the attachment.

Point / coordinates

The coordinates are entered in the format longitude, latitude, altitude. Altitude is optional. Altitude must be given in meters.


Placemark Action Target (PAT)

NOTE

Placemark Action Target feature can be used only by Wikitude Webservice Worlds (Wikitude Worlds).

Description

For each Placemark, Placemark Action Target Extension allows to specify callback URLs which are triggered when an event occurs.

Target (required)

A Target is an event (action) that occurs in Wikitude World Browser, triggered by a user. The occurrence of a target triggers an execution to be executed. A target is always related to a POI, and a POI can have multiple targets.

Currently specified targets are:

Target Name Description("When should the execution be executed?")
CLICK_MAP as soon as the user clicks on the POI in the map view
CLICK_CAM as soon as the user clicks on the POI in the cam view
VIEW_DETAILS as soon as the POI's detail view is displayed
VISIT_WEBPAGE as soon as the user opens up the POI's webpage
WRITE_EMAIL as soon as the user clicks on the email of a POI
CALL as soon as the user starts to call the POI
ROUTE_TO as soon as the user starts routing to the POI

Tags

wikitude:targets

Contains all targets defined for a Placemark.

wikitude:target

Defines an action target.

Attributes

Name Required Description
name yes identifies on which event to trigger an execution(s). E.g. ROUTE_TO.
Currently supported targets are describe above.
group no A target might have a group attribute. Consequently, targets whose have the same group's value (integer) form a Group. Those targets in the same group should not report more than once in the same session.

Group Attribute

 					
    					<wikitude:target name="CLICK_CAM" group="1">
    					....
    					<wikitude:target name="VIEW_DETAILS" group="1">
    					...
    					<wikitude:target name="VISIT_WEBPAGE" group="1">
    					...
The above example indicates that CLICK_CAM, VIEW_DETAILS and VISIT_WEBPAGE events should be reported as soon as they occur. Actually, they form a Group called "1".
Consequently, for the same session and same POI if *one* (e.g. VIEW_DETAILS) of those three events occurs once then the others should not be reported (e.g. CLICK_CAM, VISIT_WEBPAGE). World viewing session is defined as time starting when the user enters a World (from dashboard or browse world screen) until he goes back to dashboard or browse world screen.
The group ID must represent an INTEGER value.

Execution (required)

Execution defines the URL plus additional information that needs to be called to report the target back to the endpoint defined.
A target can have multiple executions. In any case, all executions are executed when the corresponding target occurs.

An execution consists of

Tags

wikitude:tExecution

Defines an execution to be triggered when the event occurs.

wikitude:tUrl

Defines an URL to be called when the event occurs.

wikitude:tHeaders

Containes all headers to be append to the REQUEST sent to the specified URL.

wikitude:tHeader

Defines a key/value pair for a header to be append to the REQUEST.

wikitude:tHeaderKey

Defines the key of a key/value pair.

wikitude:tHeaderValue

Defines the value of a key/value.

Replacements (optional)

The replacement strings can occur in the URL or the header value fields and are replaced by the Wikitude World Browser on execution. Replacement strings are always capital case and can contain underscores. They are always enclosed in %% characters.

Currenty specified replacement strings are:

Original string to be replaced Replacement
IP the IP of the client phone
USER_AGENT the currently used user agent on the device
DEVICE the device (Android,iPhone3GS,BlackBerry, etc.)
OS the operating system of the device
ACTION_TIME Time action occurred in format "yyyy.mm.dd.HH.mm.ss" e.g. 2011.08.10.19.02.59
LATITUDE_INT User's latitude as integer in format of 8-digit. E.g. 41946554
LONGITUDE_INT User's longitude as integer in format of 8-digit. E.g. 12485504
LATITUDE_DEC User's latitude as decimal. E.g. 41.946554
LONGITUDE_DEC User's longitude as decimal. E.g. 12.485504

Last Update, 23rd January 2012, 10:40 CET