Documentation

Android Reference

This page provides detailed information for the classes and methods in the AR Cloud SDK.

class ARCloudSession

ARCloudSession is the main access point to ARCloud. It is used in conjunction with the ARCore’s ARCoreSession to provide a new, shared, and persistent AR experience.

class ARCloudAnchor

ARCloudAnchor represents a point with associated orientation (coordinate frame) in server-side map.

enum ARCloudSessionState

ARCloudSessionState represents the different states AR Cloud session can be in.

enum ARCloudError

ARCloudError contains the list of possible errors with explanations of when they can occur.


class ARCloudSession: MonoBehaviour

public string apiKey

API Key used for authorization on server. For more information about obtaining the token see Generating API key.

Handling state changes

public event onChangeStateFunc onChangeState;

Occurs when the session state changes. See ARCloudSessionState for the possible states in which the session can be.

public delegate void onChangeStateFunc(ARCloudSession session, ARCloudSessionState state);

Represents the method that will handle the change of the session state. When the state is normal everything works as expected. In the other states you will usually want to notify the user and limit displaying the content.

Parameters:

  • session - Instance of ARCloudSession which generated this message.
  • state - The new ARCloudSessionState that the session has adpoted.
public event onFailFunc onFail;

Occurs when the session runs into a problem and cannot be recovered. See ARCloudError for the possible errors that can occur.

public delegate void onFailFunc(ARCloudSession session, ARCloudError error);

Represents the method that will handle the case when the AR Cloud session has failed and will not continue. This can happen right after initialization (e.g., problems with authentication) as well as during a session (e.g., device loses connection, etc.).

Parameters:

  • session - Instance of ARCloudSession which generated this message.
  • error - The ARCloudError that has happened and caused this session to terminate.

Note

When active, AR Cloud communicates with the server to localise the device in the AR Cloud map. Active session involves sending visual information and sensor data over the network and results in network usage similar to what you can experience during a video call. When Inactive, AR Cloud SDK suspends all requests and stops updating any anchors that have been added to the scene. No previously added anchors will be removed from the session.

Using Anchors

public void CreateAnchor(GameObject gameObject, Action<ARCloudAnchor, ARCloudError> handler)

Create anchor from GameObject and start maintaining it in the current session. New anchor is asynchronously created on the server.

Parameters:

  • gameObject - Anchor will be created from this GameObject.
  • handler - Handler is called when the request is processed. If there was no issue, it will be called with an ARCloudAnchor and error will be null. Otherwise, an error is passed with an explanation.
public void retrieveAnchor(string identifier, Action<ARCloudAnchor, Error> handler)

Download an anchor from the server and start tracking it in the current session. The anchor needs to be already registered on the server. Otherwise, this function will return an error. If position of the anchor changes, it is updated automatically. You should not change its position or orientation directly. Add child nodes and manipulate those instead.

Parameters:

  • identifier - Unique identifier of anchor you would like to add. It can be obtained using identifier at the time you create an anchor. You need to keep track of those identifiers in your app logic.
  • handler - Handler is called when the request is processed. If there was no issue, it will contain ARCloudAnchor with the result and no error is set. Otherwise, an error is set with an explanation.
removeAnchor(ARCloudAnchor anchor)

Remove tracked anchor from the current session. This will affect only the current session. Anchor will still be available in the cloud for use.

Parameters:

  • anchor - Anchor to be removed.

class ARCloudAnchor: MonoBehaviour

ARCloudAnchor represents a point with associated orientation (coordinate frame) in server-side map.

public string identifier

Identifier that can be used to access the same anchor across multiple sessions.

public bool isValid

State of the anchor.


enum ARCloudSessionState

normal

AR Cloud SDK is working optimally, the application can be used by the user.

limited

AR Cloud SDK is degraded, the application might be used by the user if the degraded performance is good enough for the use case, but it is not advised.

notRunning

The session has not been started or has been stopped by user or because of a failure.


enum ARCloudSessionError

notRunning

Trying to execute operation on session that is not running.

anchorNotFound

Requested anchor was not found on the server.

networkErrorUnreachable

The network operation (creating and retrieving anchors) has failed because of a timeout.

authenticationFailed

The API key you have provided is not valid. Please check that you have used a valid API key.

cannotCreateAnchor

Request to create anchor has failed. This can occur when the ARCloud session encounters issues while creating the Anchor.

arCoreNotAvailable

arCore is not available.

locationServicesNotAvailable

App is not allowed to use Location Services.

cameraNotAvailable

App is not allowed to use the camera.