ARML 1.0 Specification for Wikitude

Developer Specification for ARML 1.0 Support of the Wikitude World Browser.

Index

Versioning

This document describes the proprietary ARML 1.0 file format currently used in the Wikitude World Browser. If you are looking for the official OGC Candidate Standard ARML 2.0, please click here.

Introduction

ARML 1.0 is built on a subset of KML. The ARML 1.0 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 1.0 Example

When you create an ARML 1.0 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:target name="ACTION_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

Document Structure

An ARML 1.0 document starts with a kml tag, which is the root tag as described by the KML standard. Additionally to the standard KML namespace the ARML 1.0 namespace and Wikitude specific namespaces need to be added.

Namespaces

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 1.0 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

The kml tag contains only one Document tag, which contains the entire ARML 1.0 information.
An ARML 1.0 document consists of 2 main parts, which are described below:

ar:provider

Identifies a World. 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

Elements

Name Description Required
ar:provider Reference to the content provider definition. yes
ar:name Name of the content provider. This name will be used to display the content provider in the settings and bookmarks menu of the browser. yes
ar:description Description of a content provider that provides additional information about the content displayed. no
wikitude:providerUrl 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. no
wikitude:tags 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. no
wikitude:logo Logo displayed on the left bottom corner on Wikitude when an icon is selected.
Format: 96x96 pixel, transparent PNG		 yes
wikitude:icon The icons are displayed in the cam view of Wikitude to indicate a point of interest (POI).
Format: 32x32 pixel, transparent PNG		 yes
wikitude:shortName A short name for your World, should only be up to 20 characters, to be used when there's not enough space. no
wikitude:promotionText A promotion text describing your World in more details. no
wikitude:promotionGraphic A graphic advertising your World.
Format: 180x120 pixel, transparent PNG		 no
wikitude:hiResIcon A high resolution icon for your World which can be included in features.
Format: 512x512 pixel, transparent PNG		 no
wikitude:featureGraphic A graphic spotlighting your World in promotions.
Format: 1024x500 pixel, transparent PNG		 no
wikitude:noPromotion Opt-out from being promoted. (defaults to false) no

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

Elements

Name Description Required
ar:provider Reference to the content provider definition. yes
name Name of the POI. Displayed as POI title. yes
description Description of the POI. Currently no HTML formatting is allowed. no
wikitude:info Additional information about a POI that is displayed in the bubble no
wikitude:targets A list of Placemark Execution Targets (PET) which allow the developer to call URLs on occurance of certain user-triggered events (like a click) no
Point Coordinates wrapped in coordinate tag (see example above) entered in the format longitude, latitude, altitude. Altitude is optional. Altitude must be given in meters. yes.

Elements for wikitude:info

Name Description Required
wikitude:thumbnail 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		 no
wikitude:hiResImageUrl 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		 no
wikitude:markerIconUrl Specific an image url which points to an image used as a marker icon. If it is not given then default will be the related World's icon.
Available on Android, iPhone and BlackBerry.
Format: 32x32 pixel, PNG		 no
wikitude:phone 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. no
wikitude:url Link to a web page that contains additional information about the POI.
The element has the following optional attribute
  • name: Used to display the name of the link
 no
wikitude:email Write the person/organization an email directly from Wikitude. no
wikitude:address Address of the POI. Also used to route to the location of the POI. no
wikitude:attachments Defines a section containing a list of attachments for the POI. The element contains a list of wikitude:attachment elements, which follow the following structure. no

wikitude:attachment

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)

Elements

Name Description Required
wikitude:attachment-url 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. yes
wikitude:attachment-thumbnail Used to display a thumbnail of the attachment. no

Placemark Execution Target (PET)

NOTE

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

Description

For each Placemark, Placemark Execution 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

Elements

Name Description Required
wikitude:targets Contains all targets defined for a Placemark. yes
wikitude:target Defines an action target. See additional attributes. yes

Attributes of wikitude:target

Name Description Required
name identifies on which event to trigger an execution(s). E.g. ROUTE_TO.
Currently supported targets are describe above.		 yes
group 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. no

More detail for 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

Elements

Name Description Required
wikitude:tExecution Defines an execution to be triggered when the event occurs. yes
wikitude:tExecution Defines an execution to be triggered when the event occurs. yes
wikitude:tUrl Defines an URL to be called when the event occurs. yes.
wikitude:tHeaders Containes all headers to be append to the REQUEST sent to the specified URL. yes
wikitude:tHeader Defines a key/value pair for a header to be append to the REQUEST. yes
wikitude:tHeaderKey Defines the key of a key/value pair. yes
wikitude:tHeaderValue Defines the value of a key/value. yes

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, 23th April 2012, 12:00 CET