Using the VuMark Generation API

The VuMark Generation API is a web service for generating printable instances of a VuMark. These instances are delivered as a graphics file that encodes the instance ID provided with the generation request. This ID may be in one of several data formats.

To generate VuMark instances, you'll need to create a VuMark database in the Target Manager and upload your VuMark template as an SVG file. You'll be able to obtain a set of keys for that database that you can use when calling the VGA API. See: How To Create a New VuMark Database

Note the VuMark Generation API is only available for Pro licensees.

In order to create VuMark instances, you'll need to have a Vuforia developer account, and to generate a license for your app in the License Manager. Once you've created a license, go to the Target Manager and create a VuMark database; this will provide you with a server-access key to authenticate your calls to the VuMark generation service.

See: How To Create a New VuMark Database

You'll also need to add your VuMark design to your database by uploading the design as an SVG file to the Target Manager.

See:
How To Add a VuMark to a Database
VuMark Design Guide
Designing a VuMark in Adobe Illustrator

API Specification


Authentication

All requests to the Vumark Generation API need to be authenticated. The authentication scheme is described in this section.
Authentication is uses a server-access key pair in the form of {server_access_key, server_secret_key} which authenticates the user and authorizes him/her to access a VuMark database for instance generation. You can find this key pair in the Database Access Keys tab for your VuMark database.

The standard HTTP Authorization header is used to pass authentication information. It has the following form:

Authorization: VWS {server_access_key}:{Signature}


Where:

  • VWS stands for Vuforia Web Service.
  • The server_access_key identifies the server_secret_key that was used to compute the signature, and (indirectly) the VuMark database for which the request is.
  • The signature is a hash-based Message Authentication Code (MAC) [2]. Following is pseudo-grammar that illustrates the construction of the signature (\n means the Unicode code point U+000A).
Signature = Base64(HMAC-SHA1(server_secret_key, StringToSign ) ) );

StringToSign = 
  HTTP-Verb + "\n" +
  Content-MD5 + "\n" +
  Content-Type + "\n" +
  Date + "\n" +
  Request-Path;


Where:

  • HTTP-Verb: The HTTP method used for the action. Example:GET, POST, etc.
  • Content-MD5: The hexadecimal MD5 hash of the whole request body (from first boundary to last one, including the boundary itself). Use an empty string for request types without request body, i.e. MD5( ).
  • Content-Type: the content-type of the request body (e.g. multipart/form-data). Use an empty string for request types without request body.
  • Date: Current date, e.g.:Sun, 22 April 08:49:37 GMT. The data format must exactly match the Date that is sent in the Date header.

Notes:

  • A valid time-stamp (using the HTTP Date header) is mandatory for authenticated requests.
  • TLS 1.2 or above with server authentication is required for the API. Plain HTTP requests and requests sent to another port than 443 will be rejected.

Instance Generation

Request:

  • Method and URL: POST https://vws.vuforia.com/targets/<target-uuid>/instances
  • Authentication header: VWS Authentication header using the access-key/secret-key associated to a VuMark database (see above)
  • Date header
  • Content-Type header: application/json
  • Accept header: Specifies desired output format. One of image/svg+xml, image/png or application/pdf
  • Body encoded as JSON with the following fields:
Field name Type Mandatory Description
instance_id String yes Instance ID to be encoded in the vumark bits.
The maximum length of the instance_id is determined by the ID length property of the VuMark target. The ID length is defined in the VuMark's SVG file as part of the Illustrator design workflow.

Depending on the VuMark type the following characters and string lengths are allowed:
  • Numeric type: decimal digits 0-9 are allowed, e.g. 123456 . The submitted instance_id must be positive and smaller or equal to the max ID property of the vumark. The ID length specifies the number of bits used to encode the instance_id.
  • Bytes type: HEX representation, 0-9, a-f lowercase characters are allowed, e.g. 3fa50b . ID length determines the number of bytes in the instance id; the submitted hex-string must have exactly 2 * ID length hex characters.
  • String type: Printable ASCII characters are allowed, e.g. TAR-0003 . The submitted instance_id must have between 1 and ID length characters.


Request body example:

{

   instance_id :  TAR-0003 

}

Response (Success case):

  • Content-type header: One of image/svg+xml, image/png or application/pdf
  • HTTP Status Code: 200 OK
  • Binary body containing the file in SVG, PNG or PDF format


Response (Error case):

  • Content-type header: application/json
  • HTTP Status Code: 4xx or 5xx (see table below)
  • Body: JSON object with the following fields:
    • transaction_id: unique transaction id
    • result_code: Predefined string specifying the error cause (see below)
result_code HTTP Status Code Error cause
InvalidInstanceId 422 Specified instance ID has illegal illegal characters for the given vumark type, or id is too short or too long.
QuotaExceeded 403 No more instances can be created using the license that is associated to the VuMark database
TargetStatusNotSuccess 403 The VuMark target is currently processing or is in Failed state.
InvalidTargetType 422 The specified target is not a VuMark target
LicenseCheckFailed 403 According to the license state and type, this request can not be executed
AuthorizationFailed 401 General authentication problem

Note: Standard HTTP error codes and unspecified body may also be returned by the API

Response body example (failure):

{

   transaction_id :  a8b8c78b856c56a ,

   result_code :  LicenseCheckFailed 

}