Skip to content

ArTarget Handler

Description#

The ArTarget Handler is the handler in charge of wrapping the functionalities of the ArTargetImageAndMedia module (also called Experience module in the EMS).

The core purpose of this module is to manage your app’s Ar Experiences without needing to recompile your application, but that same architecture can be used to fit your app’s requirements.

Please refer to the Data Model for more information.

There are two types of content present in this Handler:

  • Asset: Contains the experience data for display purpose.

  • ArTarget: Contains additional experience data which can be used to create, update and delete experiences. Requires authentication to be used, available via the Account Handler’s Login method (or a ChannelManager level token).

Based on the requirements of your app, Asset might be enough. For instance, if your app simply displays the content from the EMS and augment it using AR, there is no need to prompt your users to authenticate, and calls like ArTargetHandler.GetChannelExperiences( ) are sufficient.

Note

In order to use the ArTargetHandler, you need to add the following namespace: using Appearition.ArTargetImageAndMedia;

Some of these features have offline capability. This means that if the user has accessed those functionalities at least once, the data downloaded (response and media)

All methods included inside the ArTargetHandler will be explained below.

Handler Structure#

The handler’s content can be split into 3 categories:

  • Handler Settings: defines how and where data of each type will be stored.

  • Handler Processes: all the functionality related to the EMS. When wanting to fetch EMS Data, you will be calling those processes.

  • Handler Internal: contains functionality related to downloading and saving files. Those are hidden but can be modified if need arises.

Process Structure#

A process is one or several APIs wrapped together to represent a specific functionality and exposed to the developer.

Each process is built using a specific template:

  • Processes use the information stored in the AppearitionGate’s profile. The ChannelId may be changed in the process’s parameters.

  • Each process has both a void method and an IEnumerator method. If a process is called GetChannelExperiences, its IEnumerator will be called GetChannelExperiencesProcess.

  • Each process contains several overloads, presenting various optional parameters. Some of which appear for every process. Those will be shown below.

Template parameters Type Description
channelId Int (optional) Default: The channel entered in your profile. The channel you want to get the assets from.
onSuccess Action Triggered when successful. Contains any relevant data fetched from the EMS, if any.
onFailure Action Triggered when failed. Contains the error message from the EMS.
onComplete Action Always triggered at the end of the process. The bool tells whether this process was successful.

Asset Processes#

The processes related to Assets are meant to be used for reading experiences in the EMS rather than managing them.

An example of an app that uses Assets rather than ArTargets is the ArDemo sample project, where media get displayed on the top of a target image once picked up by the smartphone’s camera.

Below are all the processes which uses Assets.

Get Channel Experiences#

Details#

Authentication Requirement: Any token
Offline Capability: Yes
Void: ArTargetHandler.GetChannelExperiences(parameters);
IEnumerator: ArTargetHandler.GetChannelExperiencesProcess(parameters);

Description#

Fetch the data related to the Experiences as stored in the EMS. This data is modeled to be read but not to be edited.

In order to create Experience data on the EMS, check out this guide:
http://d2x6st1ke820kd.cloudfront.net/sdk/unity/making-an-ar-app/#22_ems_content_setup

Optionally, it is also possible to download the content of those Experiences, including Target Images and Media.

When working with an AR App using a Cloud ArProvider, we usually use the AssetId to match an Asset with the provider’s metadata.

We recommend checking our ArDemo for further information on this topic here: http://d2x6st1ke820kd.cloudfront.net/sdk/unity/making-an-ar-app/

Example#

IEnumerator Start()
{
    //Prepare a document
    List<Asset> myExperiences = new List<Asset>();

    //Get the experiences
    yield return ArTargetHandler.GetChannelExperiencesProcess(emsData => myExperiences.AddRange(emsData));

    //Do something with the data now
    for (int i = 0; i < myExperiences.Count; i++)
        Debug.Log("Asset Id: " + myExperiences[i].assetId);
}

Parameters#

Unique Parameters Type Description
reusableList List (optional) Default: Null. A list that will be emptied and reused for performance purpose.
downloadTargetImages Bool (optional) Default: false. Whether the target images should be downloaded and stored locally.
downloadContent Bool (optional) Default: false. Whether the experience content should be downloaded and stored locally.
downloadPreDownloads Bool (optional) Default: false. Whether the media marked as Pre-Download should be downloaded and stored locally.

Get Specific Medias For A Given Asset#

Details#

Authentication Requirement: Any token
Offline Capability: No
Void: ArTargetHandler.GetSpecificMediasForAGivenAsset(parameters);
IEnumerator: ArTargetHandler. GetSpecificMediasForAGivenAssetProcess(parameters);

Description#

This process can be used to query media which are part of an asset on the EMS. For instance, if an asset contains a large amount of media and you wish to get all the media whose MediaType is a certain value, this process can do that.

Optionally, it is possible to download all the content related to the medias picked up by this query.

The reason why you might want to handle this type of query on the EMS rather than on the EMS can purely be because of project architecture reasons, or because you have obtained the AssetId by other means, such as via an ArProvider when picking up a target.

Example#

// This method is called once an ArProvider recognized a target using cloud capability (like vuforia).
// Check out the ArDemo to see more about this.
void OnTargetImagePickedByArProvider(string metadata)
{
    Dictionary<string,string> queryParams = new Dictionary<string, string>();

    //In this case, we want to get all the Media which are videos, and download them.
    queryParams.Add("mediaType", "video");

    ArTargetHandler.GetSpecificMediasForAGivenAsset(metadata, true, queryParams, mediaFiles => {

        for(int i = 0; i < mediaFiles.Count; i++)
        Debug.Log("Media file found: " + mediaFiles[i].fileName);
    });
}

Parameters#

Unique Parameters Type Description
assetId String Default: Required. The assetId of the asset you wish to query.
downloadContent Bool (optional) Default: true. Whether the content of the media picked up by this query should be downloaded and stored locally.
queryingDictionary Dictionary<string,string> Default: Required. The content of the query, where a Key is a variable in a MediaFile, and the Value is the expected value of that variable.

ArTarget Processes#

ArTargets are mainly used to manage the experiences from the application. The ArTarget inherits from Asset, but contains additional variables used for management purpose.

Below are the processes which use ArTargets, most being CRUD related functionalities.

Create ArTarget#

Details#

Authentication Requirement: ChannelManager or authenticated token
Offline Capability: No
Void: ArTargetHandler.CreateArTarget(parameters);
IEnumerator: ArTargetHandler.CreateArTargetProcess(parameters);

Description#

Allows the creation of an experience. From there onwards, you are free to upload content.

By default, this process only creates an empty experience or an experience with a TargetImage, but if you wish to add medias to it, keep the arTargetId and add medias using the UploadMedia process.

Example#

//Any texture. You may drag it from the inspector or load a picture however you want.
public Texture newTargetImage;

IEnumerator Start()
{
    //Create an experience using a name and a target image.
    yield return ArTargetHandler.CreateArTargetProcess(newTargetImage, "MyExperience");
}

Parameters#

Unique Parameters Type Description
newTargetImage Texture (optional) Default: Null. The picture you want as a TargetImage for this experience.
experienceName String Default: Required. Name of the experience as on the EMS.
filename String (optional) Default: UploadedTargetImage.jpg. The filename of the newTargetImage, if any.

Upload Media#

Details#

Authentication Requirement: ChannelManager or authenticated token
Offline Capability: No
Void: ArTargetHandler.CreateMedia(parameters);
IEnumerator: ArTargetHandler.CreateMediaProcess(parameters);

Description#

Allows to add a new media to your existing Experience using an ArTargetId. Make sure that the MediaType and MimeType have been entered correctly in the MediaFile if you decide to upload a file as part of this media. Do also note that this media data can be edited later on using the UpdateMedia process, or a file can be added using the ReplaceMediaContent process.

Example#

Here is an example of the simplest way to this the CreateMedia process.

IEnumerator Start()
{
    ArTarget myNewExperience = null;

    //In this case, we might want to create a new Experience without a target image.
    yield return ArTargetHandler.CreateArTargetProcess(null, "My Experience", "", newTarget => 
        myNewExperience = newTarget
    );

    //In this case, we just want to create a simple Media with only text inside.
    MediaFile myMedia = new MediaFile();
    myMedia.mediaType = "Text";
    myMedia.text = "Hello!";

    //And now we upload it.
    yield return ArTargetHandler.CreateMediaProcess(myNewExperience.arTargetId, myMedia, true);
}

Parameters#

Unique Parameters Type Description
reusableList List(optional) Default: Null. Will create a new one. A list that will be emptied and reused for performance purpose.

Process Name#

Details#

Description#

Example#

Parameters#

Unique Parameters Type Description
reusableList List(optional) Default: Null. Will create a new one. A list that will be emptied and reused for performance purpose.