Using the VuMark Generation API

This page concerns the Vuforia Engine API version 9.8 and earlier. It has been deprecated and will no longer be actively updated.

The VuMark Generation API is part of Vuforia Web Services 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.

In order to create VuMark instances, you will need to have a Vuforia Engine developer account, and a license for your app from the License Manager. Once you have created a license, go to the Target Manager and create a VuMark database and upload your VuMark template as an SVG file; 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

NOTE: Unlimited use of the VuMark Generation API is only available for Pro licensees.

If you are yet to have made a VuMark template, consult the following articles on how to design on in Adobe Illustrator. 

See:

VuMark Design Guide

Designing a VuMark in Adobe Illustrator

How To Add a VuMark to a Database

API Specification

Authentication

All requests to the Vumark Generation API need to be authenticated. The authentication scheme is described in this section.

Authentication 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 of 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]. The following example 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.
• Request-Path: The path needs to include the entire URL of the request, so when generating a specific VuMark instance the Request-Path would be "https://vws.vuforia.com/targets/{target-id}/instances/{instance_id}", where target_id is the specific ID of the template from which the instance with the instance_id is generated.

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:

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)

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 
}

Learn More

Vuforia Web Services

VuMark API Overview

How to Work with VuMark Databases