The VuMark Generation Web API allows 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 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
If you are yet to have made a VuMark template, consult the following articles on how to design one in Adobe Illustrator.
See:
Authentication
All requests to the VuMark Generation API need to be authenticated using the Vuforia Web Services (VWS) signature scheme described in the Vuforia Web API Authentication.
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.
- 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 |
|
String |
yes |
Instance ID to be encoded in the VuMark bits.
|
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).
Error Code |
HTTP Status Code |
Description |
|
Unprocessable Entity (422) |
Specified instance ID has illegal characters for the given VuMark type, or id is too short or too long. |
|
Forbidden (403) |
No more instances can be created using the license that is associated to the VuMark database. |
|
Forbidden (403) |
The request could not be completed because the target is not in the success state. |
|
Unprocessable Entity (422) |
Target Type is invalid (e.g. trying to generate a VuMark of a Cloud Target). |
|
Forbidden (403) |
According to the license state and/or type, this request can not be executed. |
|
Unauthorized (401) |
General authentication problem. |
|
Bad Request (400) |
The accept header does not contain a valid VuMark output format. See the description of the Accept header for the list of valid output formats |
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"
}