Cloud Recognition API Overview

Use a cloud database to detect and track amongst millions of Cloud Image Targets. This article presents the general steps to implement Cloud reco in native.

A Cloud Image Target is an Image Target stored in the Vuforia Servers. This allows you to store, detect, and track between millions of Image Targets from a single Cloud Database. Upload your Cloud Image Targets using the Target Manager. See also Cloud Targets Web API.

General Setup

Please see the Vuforia Engine Lifecycle for a general introduction to the Vuforia Engine lifecycle. The Engine is required for creating and using Observers.

Create a Cloud Image Target Observer

Cloud Recognition is handled by the Engine via the Cloud Image Target Observer. Configure the Cloud Recognition with VuCloudImageTargetConfig and detect recognition events with VuCloudImageTargetObservationTargetInfo.

Differently from other tracking API in the SDK, where you get continuous tracking updates via pull mechanisms from the State, Cloud Recognition does not necessarily get continuous information; you need to register a handler for getting updates. Do this with the vuCloudImageTargetObserverRegisterHandlers. Once the Observer is created and activated, search results will be reported via the registered callback function VuCloudImageTargetObservationsHandler.

Create Observer from VuCloudImageTargetConfig

To use Cloud Recognition, you first need to initialize the system and set the credentials for your cloud database. The creation process requires an active network connection and runs asynchronously.

The following creates the Cloud Image Target Observer. It is activated by default.

VuObserver *observer = nullptr;

VuCloudImageTargetConfig cloudImageTargetConfig = vuCloudImageTargetConfigDefault();
cloudImageTargetConfig.userAuth = "<your credentials>";
cloudImageTargetConfig.secretAuth = "<your credentials>";

VuCloudImageTargetCreationError creationError;
if (vuEngineCreateCloudImageTargetObserver(engine, &observer, &cloudImageTargetConfig, &creationError) != VU_SUCCESS)
    // handle observer creation errors
    switch (creationError)
        // handle the "NO NETWORK" error

        // handle other VU_CLOUD_IMAGE_TARGET_CREATION_ERROR... errors


NOTE: Find your authentication keys in the Cloud Database’s details in the Target Manager.

Starting and stopping a Cloud Recognition search

Register handlers for Cloud Image Targets with VuCloudImageTargetObservationsHandler. This observation handler is triggered whenever a new Cloud Image Target is detected. You can then choose to create an Image Target Observer with vuEngineCreateImageTargetObserverFromCloudObservation() to start tracking the image.

MyClientData clientData; /* placeholder for an app-specific data structure */
vuCloudImageTargetObserverRegisterHandlers(observer, &recoEventHandler, &queryErrorHandler, &clientData);

Handling Search Results

At runtime, you need to handle new Cloud Recognition search results and, if desired, create the Image Target Observer for tracking.

Below is a sample code snippet that inspects information about the detected targets via vuCloudImageTargetObservationGetTargetInfo. Target info includes name, unique id, metadata, and tracking rating.

From the observations, the sample then creates an Image Target Observer with vuEngineCreateImageTargetObserverFromCloudObservation.

recoEventHandler(const VuObservationList *observations, void *clientData)
    MyClientData *myClientData = static_cast<MyClientData *>(clientData);

    int32_t numObservations = 0;
    vuObservationListGetSize(observations, &numObservations);

    // iterate through all Cloud Image Target observations received via reco event
    for (int i = 0; i < numObservations; i++)
        VuObservation *observation = nullptr;
        vuObservationListGetElement(observations, i, &observation);

        // read Cloud Image Target information
        VuCloudImageTargetObservationTargetInfo cloudImageTargetInfo;
        vuCloudImageTargetObservationGetTargetInfo(observation, &cloudImageTargetInfo);
        // print("Cloud Image Target '%s' recognized",;

        // create Image Target observer using Cloud Image Target observation
        VuImageTargetCloudObservationConfig cloudObservationConfig = vuImageTargetCloudObservationConfigDefault();
        cloudObservationConfig.observation = observation;
        cloudObservationConfig.activate = VU_TRUE; // automatically activate if engine is running

        VuObserver *targetObserver = nullptr;
        VuImageTargetCloudObservationCreationError creationError;
        if (vuEngineCreateImageTargetObserverFromCloudObservation(engine, &targetObserver, &cloudObservationConfig,
                                                                  &creationError) != VU_SUCCESS)
            // error handling

For more information on counting and handling the Cloud Recognition search results, please see Counting Cloud Recognition Events.

Error Messages

Errors that are detected asynchronously after the Observer is created are reported via the error handler callback. Here is an example of how to write such a handler:

queryErrorHandler(VuCloudImageTargetQueryError queryError, void *clientData)
    MyClientData *myClientData = static_cast<MyClientData *>(clientData);

    // handle query-related errors
    switch (queryError)
        // handle "authorization failed" errors

        // handle other VU_CLOUD_IMAGE_TARGET_QUERY_ERROR_... errors

The following error codes may be returned by the VuCloudImageTargetQueryError. This table lists the codes alongside their meanings.





No network connection



Server not found, down, or overloaded



Credentials are wrong or outdated



The specified project was suspended



Low frame quality has been continuously observed



SDK version outdated



Client/Server clocks too far apart



No response to network request after timeout

Can this page be better?
Share your feedback via our issue tracker