Documentation

iOS 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 ARKit’s ARSession to provide a new, shared, and persistent AR experience.

class ARCloudAnchor

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

protocol ARCloudSessionDelegate

ARCloudSessionDelegate can be used to respond to the changes in the session and anchors.

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

Running a Session

func init(apiKey: String, sceneView: ARSCNView)

Create an instance of ARCloudSession with a developer API key. You learn how to get one on Get an API key page.

Parameters:
  • apiKey - used for authentication on server.
  • sceneView - ARSCNView with an instance of ARKit’s ARSession.
func run()

Upon calling this method, ARCloud starts communicating with the server to localise the device in the ARCloud map. You cannot create or retrieve any shared AR content if the session is not running. You usually call this method right after you call run(_:options:) on your ARSession.

Note

Running the session involves communicating visual information and sensor data over the network and results in a network usage similar to what you can experience during a video call.

func pause()

After calling this method ARCloud 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. You usually call this method right before you call pause() on your ARSession.

Responding to localization state

var delegate: ARCloudSessionDelegate?

Provides access to current tracking state and anchor updates.

Using Anchors

func createAnchor(from node: SCNNode, _ handler: (ARCloudAnchor?, Error?) -> Void)

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

Parameters:

  • node - Anchor will be created from this node.
  • 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 nil. Otherwise, an error is passed with an explanation.
func retrieveAnchor(identifier: String, _ handler: (ARCloudAnchor?, Error?) -> Void)

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.

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.
func removeAnchor(_ anchor: ARCloudAnchor)

Remove tracked anchor from the current session.

This will affect only current session. Anchor will still be available to other devices.

Parameters:

  • anchor - Anchor to be removed.

class ARCloudAnchor

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

If the position of the anchor changes, it is updated automatically. You should not change its position or orientation directly. Add child nodes and manipulate them instead.

When the anchor becomes invalid, its position is no longer updated. The associated ARCloudAnchor.node stays in the scene at the last known position. You should hide the content attached to the node or remove the node from the scene completely as soon as it becomes invalid. This will provide the best experience to the user.

let identifier: String

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

var node: SCNNode

Node representing this anchor.

let isValid: Bool

State of the anchor.


protocol ARCloudSessionDelegate

session(_ session: ARCloudSession, didChangeState state: ARCloudSessionState)

Tells delegate that the session state has changed. See ARCloudSessionState for more.

Parameters:

  • session - Instance of ARCloudSession which generated this message.
  • state - New state of the ARCloudSession.
session(_ session: ARCloudSession, didFailWithError error: Error)

Tells delegate that localization session failed and will not continue. This can be called either right after initialization or during a session.

Parameters:

  • session - Instance of ARCloudSession which generated this message.
  • error - An error describing the session failure reason.
func session(_ session: ARCloudSession, didUpdate anchors: [ARCloudAnchor])

Tells the delegate that the session has made the anchor become valid.

Parameters:

  • session - Instance of ARCloudSession which generated this message.
  • anchors - A list of the updated anchors.

enum ARCloudSessionState

case normal

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

case 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.

case notRunning

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


enum ARCloudError

case notRunning

Trying to execute operation on session that is not running.

case anchorNotFound

Requested anchor was not found on the server.

case networkErrorUnreachable

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

case authenticationFailed

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

case cannotCreateAnchor

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

case arKitNotAvailable

ARKit has reported ARCamera.TrackingState.notAvailable.

case locationServicesNotAvailable

App is not allowed to use Location Services.

case cameraNotAvailable

App is not allowed to use the camera.