Skip to content

LocationDemo - Experiences And Maps

An Example of creating a simple Image Marker ARFoundation application using the Appearition SDK for Unity

Description of Project#

This document explains the process of creating an image marker based augmented reality application integrating parts of Appearition’s Platform services and the Unity AR Foundation framework. The value of such integration being derived from producing an AR app with dynamic AR content that is managed and distributed by an on-line platform. This enables immediate changes to AR targets and projections without the need to re-work and compile new apps.

An approach on how to implement the Appearition SDK, specifically covering the ArTargetImageAndMedia module is the primary focus of this exercise. However, the Appearition platform also accommodates many other uses delivered by its vast set of modules that can also be integrated into your app projects. This example only covers a very basic usage of the Appearition platform.

Requirements#

  • Working knowledge of Unity functionality, including importing and using Unity packages, and configuring client apps for different types of platform deployments.

  • Usage of Unity 2020.1 or later

Tutorials on specific EMS and SDK setups are also available on this link

Appearition Unity SDK Package Location#

This sample project is mirrored by an Unity demo scene that is included with the Appearition Unity SDK package v0.7.4, which is accessible by logging into the Appearition technical portal. if you ha’e subscribed to the system you will find this in your “downloads” page. Please ensure that you follow the steps below before you import an deploy the Appearition Unity SDK package.

Note

The instructions that follow include critical Unity configuration steps that need to be completed prior to importing or using the Appearition package.

A Highlevel description of the workflow#

The steps discussed here can be defined in stages that include:

  1. Provisioning the Appearition Platform to deliver content to your Unity App

  2. Configuring your Unity App to use the Unity AR Foundation framework

  3. Installing and setting up the Appearition Unity SDK in your app to access the media objects you have provisioned for the AR session.

Register you app with Appearition’s EMS#

Once you have completed setting up your AR experiences within the Appearition EMS, the unity app that you are working on will need to access your EMS experiences. This access permission is provided to the app by you registering the app in the EMS. Follow these steps to register your app with the Appearition EMS:

  1. Click on the home button, the first icon on the right side of the Appearition portal:

  2. Click on the “API Access” link:

  3. Click on the “+Register Application” button:

  4. Type your application identifier (the Unity package name of your app) and click on the “Register Now” button:

Obtain key information needed when building your Unity app#

Note

You will need the information you obtain by following these steps when you are building your Unit app. You will get the API Token,Tenant,API URL and APIVersion by accessing swagger. For information on how to access your channel id click here:

Obtain your API Token,Tenant,API URL and API Version from Swagger#

  1. Click on the home button, the first icon on the right side of the Appearition portal:

  2. Click on the “API Access” link:

  3. Click on the “Swagger” link in the same row as your application “Application ID”:

  4. Write down the details provided by the Swagger panel. You will need these details when you start using Unity.

Obtain your Channel Id#

Note

You will need the channel Id to enable your app to use that channel. You also need the API Token,Tenant,API URL and API Version.

  1. Click on the home button, the first icon on the right side of the Appearition portal:

  2. Click on the “Your Channel List” button, just as if you were about to create or edit your AR experiences.

  3. Note down the channel Id number. Now you have the channel id you will need to use within your Unity app build.

Setting up Unity to use the AR Foundation Framework#

Unity has its own packages for managing AR experiences, however, the default state of this set up is for working with “baked” on experiences that will not change unless the app is reworked and recompiled. The Appearition Unity SDK makes use of the Unity AR Foundation framework by integrating it with its dynamic content delivery and management service, so content can be changed at any time whilst the client application is live (this includes, target markers in case of image recognition/tracking).

  1. Configure Unity to work with the ARFoundation Framework

In the Unity project you are using as your AR app you must:

  • Whilst inside the Unity Editor, install the ARFoundation packages:

    • click on Window->Package Manager.
    • once the Unity Package Manager has loaded, select the “Unity Registry” option to show all available packages.
    • Install the “ARFoundation 4.1.7” and “ARCoreXR Plugin 4.1.7” and/or “ARKit XR Plugin” (or any other XR plugins relevant to the ARFoundation system you are interested in applying). Note that once you select these options the “XR Plugin Management” component should also have been installed by the system.

  • Inside the Unity Editor, set up “Player Settings” in Unity for XR functionality:

    • Click on File->Build Settings
    • Switch to the current platform you will build for.

In this scenario we will be building an Android app, so the setting prescribed will relate to the Android Platform. However, the same steps can be followed with the exception that the iOS branch, or any other compilation branch will be followed instead.

  • Click on the “Player Settings…” button

  • Navigate to the “Graphic APIs” section and remove the “Vulcan” option.

  • Navigate to “Minimum API Level”: change it to “Android 7.0..”. Also change the “Api Compatibility Level” to “.Net4.x”

  • Navigate to “XR Plug-in Management”, select “ARCore”

*** You are now ready to import the Appearition Unity SDK package ***

Import the Appearition Unity SDK package into your Unity App#

Note

Ensure you are logged into the Appearition portal when performing the steps that follow

  1. Click on the home button, the first icon on the right side of the Appearition portal:

  2. Click on the “Download” link

  3. Now download the Appearition Unity SDK package by clicking on “Download” button

Set up the AR Foundation Demo#

  1. Import the Appearition Unity SDK package (AppearitionSDK-v0.7.4) into your already configured AR Foundation Unity App framework.

  2. This will create the following folder structure in your Unity Editor:

The Appearition\Examples\SampleProjects folder contains two file:

  • AppearitionSDK_v07.4.ArDemo_v3.0

  • ArDemo_ReaMeBeforeExtracting

Note

Really read the “ArDemo_ReaMeBeforeExtracting” and follow the instructions!!!

The instructions in the readme file are a short step guide that provide a checklist on setting up different type of app integrations. For this exercise we are interested in the “ArFoundation Integration Instructions …” segment. By paraphrasing this section we can check that we have already performed the following steps:

  • Installed the XR Plugin Management (4.0.7)

  • Installed AR Foundation (4.1.7)

  • Installed either or both ARCore XR Plugin & ARKit XR Plugin (v4.1.7)

  • Removed Vulkan from the list of Graphic APIs

  • Set Minimum API Level to Android 7.0 API lvl 24

  • Set API Compatibility Level to .NET 4.x

  • Checked that we are using XR Plugin Management and selecting ArCore

  • Checked that we are building an Android app

What you still need to do:#

  • Install the AppearitionSDK_v0.7.4_ArDemo_v3.0 package located inside Appearition\Examples\SampleProjects\

This creates a set of new folders in the Editor, including the ARDemo Folder. \ArDemo\Packages contains three packages. The most relevant for this exercise being ArDemo_ARFoundation_v4.1.7_Integration.

  • Install the ArDemo_ArFoundation_v4.1.7_Integration package found under Appearition/Example/SampleProjects/ArDemo/Packages. This creates new scenes in Appearition/Examples/SampleProjects/ArDemo/Scenes. The ARFoundation scene is “ArDemo_ARFoundation”. Select this scene to try the demo.

  • Once this scene is built in a supported device, try out the demo…

Note

You can test the Marker mode using the sample target images inside Appearition\Examples\SampleProjects\ArDemo\SampleImages or you can go to the EMS portal and use the targets images you created in your channel…

Creating EMS Content#

For more detail information on the use of the AR provisioning wizard read this segment.

The AR Provisioning Wizard: The EMS forms provisioning the AR Experiences#

The “Details” form#

The “Details” form, specially its name, provides the AR experience identifier used by the system. Click “Next”.

The “Target” form#

The “Target” form provides the details about a visual target when you are using image tracking. Click “Next.

You can now upload any image you have in your local machine by clicking on the “Upload New Image” button, or use an image you have already uploaded into the channel by clicking the “Use Existing” button.

The “Media” form#

The “Media” form provisions all the media types that you can use to project against the image tracker. You can insert one or many new media digital files that will be projected when tracking is operational in the client app by clicking the “New” button. If you want to re-use a digital media format you have included before into the channel, click on “Use Existing”.

After you click “New”, you must select its media type from the options displayed in the option box. Some options, or media types included are:{3d, Image, ModelView, transparent_video, video, video_stream, weblink, and more…}. New media types can be added by the Appearition Platform administrator..

Once you have selected the media type, then upload the digital file that contains the media object.

You must then position, scale and rotate the media object in reference to your needs. All media projections are “attached” to the tracked object, so ensure that the scale is above zero for all x,y,z values (unless you want strange or no projections!). A scale of 1,1,1 means the media will occupy the same area as the image target. Translation refers to where you want to position the object in reference to the tracked object, so a Translation of 0,0,0 anchors the media projection to the middle of the object being tracked. The rotation of the media depends on your requirements.

The “Tags” form#

The “Tags” form provides the means for the system to enable different types of access to your AR experiences.

In this case we are building an anynomous app, in which users do not need login functionality to use the app. You can also use a combination of other tags that make sense in your context. For more information on tags, click here.

The “Publish” form#

Once published, your Experience should appear normally in the list of Experiences.

Testing the Demo or any of your applications#

You are now ready to test. We usually have three ways of testing AR Content:

  • Print a target on paper and hold it on front of the camera.

  • Use the UnityRemote application to access the phone’s camera and have it aim at the Target Image picture on the computer’s Screen.

  • Build on Android/iOS and aim the camera at either the printed Target Image or the picture on the computer’s screen.

The Target Images should get picked up by Vuforia when scanning your targets, showing your content on the top of them.

Debugging AR Experiences#

Here are some tips for how to debug the ArDemo. For starters, when developing, changing the Logging Mode to Debug helps a lot, since it wot filter the Debug.Logs created by the Appearition SDK. We highly recommend setting it to Debug for the sake of visibility.

Setup Common Mistakes#

Here is a list of the common mistakes and how to solve them.

Unrelated errors in the console#

It is important to note that errors in the console related to C#, such as null reference exception, index array out of range, missing reference exception, etc, cause the code execution to stop.

If your application has reached one of those errors prior to any other errors, fix it first.

No Profile Entered#

If no profile is entered in the AppearitionGate, it will be unable to communicate with the Appearition Platform. It can be picked up by the error in the console as shown above.

Vuforia License Key not entered / mismatch#

This type of error is caused by no license key entered in the VuforiaConfiguration file. Additionally, it will happen whenever the ArCamera shows only a black screen.

To fix this, simply head over to https://developer.vuforia.com and fetch your Vuforia App License Key again and enter it inside the App License Key field on the VuforiaConfiguration file.

Appearition Platform Anonymous Token expired or mismatch#

This issue is most likely to occur upon getting the errors below:

Getting the experiences requires the lowest level of Token, but unlike Ping, still requires one. Failing this request means that you do have data entered in the AppearitionGate, but isn’t valid.

Head over to the AppearitionGate on the AppearitionManager_Ar object, and ensure all values are correctly entered.

Vuforia not finding a device#

This case occurs when the ArCamera’s VuforiaBehaviour script has its WorldCenterMode set to Device, and you aren’t running the program on a mobile device.

By default, we recommend having it set to First Target.

Vuforia not enabled#

If you have imported the ArDemo sample project but forgot to turn on Vuforia, the console might give you something like the following:

In order to fix it, head to the Player Settings and turn it on. Refer to 1.1 Setting the Unity Editor for more information.

Target Not Found?#

No Target Image attached#

While this case scenario shouldn’t be possible when creating an Experience from the EMS Portal, it can happen nonetheless when generating Data on the EMS from your application.

Ensure that your Experience has a Target Image before continuing further.

Published or Unpublished#

Experiences have a published state which determine whether or not their data will be visible using the common API to fetch the Experiences data.

An unpublished Experience shows as greyed out in the Experience List, in the EMS, like so:

In order to fix it, click on the Experience, go to the Status tab, and click on Publish. Upon success, the Target Image preview will look normal.

Image Recognition Syncing#

There is a chance that your Target Images are either not synced with your Image Recognition setup. Refer to First Run, Syncing with Vuforia Database to find more about how to sync Target Images with your Image Recognition on the Appearition Platform.

Target found but where’s my Media?#

No media attached#

While it may sound silly, this has happened to us quite a few times; whereby we have an Experience with a Target Image but forgot to add at least one Media.

As part of diagnosing for the lack of Media, checking the EMS is a must step. Refer to Appearition Platform Content Setup for more information about how to setup Medias.

Zero scale / Quad Rotation#

Nearly all non-fullscreen Medias will be using the Translation, Rotation and Scale values. If any of the Scale value is zero, the object will most likely not be displayed properly.

Additionally, depending on the type of Media, if it is rendered on a single-sided mesh (like, a quad) and X or Y rotations are greater than +90 or smaller than -90, it will not be displayed properly.

In order to change that, head over to the Experience, edit the Media, and set the Scale value properly. Refer to EMS Content Setup for more information about where to find those panels.

Application not fetching Asset data#

Ensure that that the EMS Asset List is being fetched properly. In order to achieve that, ensure that the Logging Mode is set to Debug mode as shown in Debugging AR Experiences.

Having the Debug mode enabled, ensure that you get a similar log in the console:

These logs confirm that the experiences are fetched successfully. Prior to those logs, the EMS live data isn’t on the application yet, and so cannot be displayed when the Target has been found by the AR Provider.

Contact Us#

If none of the issues are listed above, please contact us via email at: support@appearition.com

Thank you for using the Appearition platform and happy deving!