Audience

This material is intended to help experienced software developers understand how create custom touchatag application configurations using the Touchatag Configurator API.

Before reading this, you must be familiar with these concepts:

• ACS Block System
• Specification documents

Overview

You can devise your own custom touchatag Applications and make them available in the touchatag dashboard, either for your own use, or to share with other users in the touchatag user community.

The easiest way to create such an application is to create a Specification document and then use the Specification Tool to submit it. This is an excellent way to rapidly prototype your applications. However, Applications created with the Specification Tool do have a couple drawbacks:

• They do not provide an user-friendly configuration interface.
• They cannot be shared with other users through the touchatag dashboard.

The Configurator API solves both of these issues. It provides you:

• a way to present end users with a user-friendly configuration interface that integrates directly into the touchatag dashboard
• a means for submitting your Specification documents to create shareable applications

Using the Configurator API, your custom configuration interface gets inserted directly into Step 2 of the touchatag dashboard's Configurator. Such an interface is called a Configurator Applet. Configurator Applets allow your applications to accept custom user input in the touchatag dashboard's Configurator, and then assemble that custom input into a complete Specification document.

Once you have successfully created a custom application that uses your Configurator Applet, you can choose to allow every member of the touchatag community to use it, or reserve the application for your own private use.

At this time, you must request access to the touchatag Touchatag Configurator API, as detailed in Requesting Access below.

Key Concepts

Understand these concepts in order to make your own custom applications available in the configurator.

Application

Within the context of the touchatag dashboard, an application is a set of functionality that you select to configure, and then associate to tags. Some examples include the Social Business Card application, the Web Link Wheel application, and the Twitter application.

Note that in these examples, application does not refer to a web application (such as twitter) or a desktop application (such as iTunes). Instead, we are specifically referring to an action, or set of actions, that can be applied (configured and then associated) to one or more tag.

Configurator Applet

A Configurator Applet serves three coordinated functions. First, the Applet provides end users with an interface through which they can enter whatever parameters are required by an application. For example, the Music Player Application (shown above in context of the Configurator Applet) requires several parameters to configure.)

The Configurator Applet's second function is to assemble parameters into a Specification that tells the ACS how to handle tag transaction events.

The final function of a Configurator Applet is to send the Specification (properly assembled) to the ACS. Configurator Applets send the Specification to the ACS over the Configurator API.

Configurator API Workflow

The following steps describe the complete process of how a Configurator Applet fits within the overall configurator workflow:

1. After clicking Configure an application the Configurator launches. In Configurator Step 1, you select the application to Configure.

2. The user interface of Step 2 opens an IFrame, using the URL of your application, appended with ?configurationTransactionId=<ID(string)>.

Example:

3. The client browser calls the URL to your Configurator Applet from the IFrame.

4. Your Configurator Applet calls the getApplicationConfig method, using the configurationTransactionId value.

5. The ACS replies with a base64-encoded applicationConfig response.

If you are editing a previous configuration of your application (as opposed to making a new configuration), your Configurator Applet decodes the response and restores previously-set parameters into the Configurator Applet's user interface.

6. The user interface of your Configurator Applet loads in the IFrame.

7. The end user enters whatever custom input is required by your Configurator Applet, and then submits it using a confirmation button provided in your user interface.

8. Your Configurator Applet assembles a Specification, using the parameters entered by the end user and whatever other parameters your application logic adds. It then uses the updateTransaction method to send a handleRequest (which includes the Specification, an updated applicationConfig, and the configurationTransactionId) to the ACS.

9. When the ACS successfully receives the Specification, it instructs the configurator on the client system to advance to Step 3.

Implementation Details

Host Platform Requirements

A Configurator Applet must be hosted on an Internet-accessible web server.

Because the user interface for a Configurator Applet is simply a web page hosted within an IFrame, you can host your applet on any standard web application platform (JavaScript, PHP, Ruby on Rails, ASP.NET, etc.).

User Interface Requirements

The user interface of your Configurator Applet must fit within the IFrame presented by Step 2 of the Configurator.

Dimensions:

• Width: 330 pixels
• Height: 160 pixels
  Note You can use a form height greater than 160 px by enabling scrollbars.

Restoring Parameters on Edit

In most cases, when you configure your application for the first time, the input fields of your user interface should be empty. However, each time you subsequently edit that application configuration, you want the form to show the values you previously supplied. This is the purpose of the applicationConfig parameter (see workflow step 5 above).

The applicationConfig is a base64-encoded string used to store parameters set by each specific configuration of your application. Your Configurator Applet can use the applicationConfig to restore parameters that were previously set in a specific configuration of your application.

How your Configurator Applet uses applicationConfig to store and retrieve parameters is up to you.

For example, suppose you have an application that requires two input parameters: firstName and lastName. When your Configurator Applet builds the Specification, you can also assemble your parameters into a comma-separated string Doe,John, and then base64-encode the string. Your Configurator Applet can then send the base64 value to the ACS when it calls the updateRequest method. The next time you edit that application configuration, the ACS will return the same value in response to the getApplicationConfiguration method. Your Configurator Applet can then decode the response to restore the parameters.

Requesting Access

The Touchatag Configurator API WSDL file is located here:

• https://acs.touchatag.com/soap/configurator-1.0?WSDL

At this time, you must request access to the touchatag Touchatag Configurator API by emailing developer@touchatag.com, providing the following information:

• your touchatag user account name
• Application name (as you would like it to appear in the touchatag dashboard)
• Application description (optional, it will also appear in the touchatag dashboard)
• The complete URL where you will host the Configurator Applet for the application

We are working to make this an automated process. Until then, the average turnaround time for API access requests is 24 hours.

Additional Resources

Get Help

Short reference to how to get more info, includes Google Groups Etc.