Skip to Content
Quick StartReact Native

React Native

Open the native Graffity AR Cloud experience from React Native with a Turbo Native Module. JavaScript calls open(accessToken) and close(). On each platform, the module presents the same native host used in the iOS SDK and Android SDK quick starts. The host owns the SDK, permissions, AR view, and shutdown.

These docs use iOS SDK 5.6.0 and Android SDK 5.5.0.

Requirements

  • An access token from Graffity Console. Load it at runtime from your backend instead of hard-coding it.
  • React Native 0.77 or later with the New Architecture enabled (the default since 0.76). Expo apps need a development build .
  • Everything listed in the native requirements: iOS (iOS 18.0+, physical ARKit device) and Android (API 28+, ARCore-supported device, JDK 17).

How it fits together

LayerFileRole
JavaScriptspecs/NativeGraffityARCloud.tsTyped spec; Codegen generates the native interfaces from it.
iOSGraffityARPresenter.swift + RCTGraffityARCloud.mmSwift presenter for ARExperienceViewController, wrapped by an Objective-C++ module.
AndroidGraffityARCloudModule.kt + GraffityARCloudPackage.ktKotlin module that launches GraffityARActivity.

Define the module spec

Create the spec

specs/NativeGraffityARCloud.ts
import type { TurboModule } from 'react-native'; import { TurboModuleRegistry } from 'react-native'; export interface Spec extends TurboModule { open(accessToken: string): Promise<void>; close(): Promise<void>; } export default TurboModuleRegistry.getEnforcing<Spec>('NativeGraffityARCloud');

Configure Codegen

Add codegenConfig to your app’s package.json. Replace com.example.app with your Android package.

package.json
{ "codegenConfig": { "name": "AppSpecs", "type": "modules", "jsSrcsDir": "specs", "android": { "javaPackageName": "com.example.app" }, "ios": { "modulesProvider": { "NativeGraffityARCloud": "RCTGraffityARCloud" } } } }

Codegen runs during pod install on iOS and during the Gradle build on Android. See React Native’s Turbo Native Modules guide .

iOS

Install the SDK

Set the deployment target to 18.0 in ios/Podfile (platform :ios, '18.0') and in the app target. Open ios/<YourApp>.xcworkspace, then follow Install the SDK to add the GraffityARCloud package product to your app target. Add the camera and location descriptions to Info.plist.

Add the AR host

Copy the complete UIKit ARExperienceViewController into your app target. It retains the SDK, embeds its view, and provides a native Close button that shuts down the session.

Add the Swift presenter

The presenter keeps a weak reference to the open host, so it clears automatically when the user taps Close.

ios/GraffityARPresenter.swift
import UIKit @objc(GraffityARPresenter) @MainActor final class GraffityARPresenter: NSObject { @objc static let shared = GraffityARPresenter() private weak var host: ARExperienceViewController? @objc(openWithAccessToken:presenter:completion:) func open( accessToken: String, presenter: UIViewController, completion: @escaping (NSError?) -> Void ) { guard host == nil else { completion(NSError( domain: "GraffityAR", code: 1, userInfo: [NSLocalizedDescriptionKey: "Close the current AR session first."] )) return } do { let controller = try ARExperienceViewController(accessToken: accessToken) controller.modalPresentationStyle = .fullScreen host = controller presenter.present(controller, animated: true) { completion(nil) } } catch { completion(error as NSError) } } @objc(closeWithCompletion:) func close(completion: @escaping () -> Void) { guard let host else { completion() return } self.host = nil Task { await host.endSession() host.dismiss(animated: true) { completion() } } } }

Add the Objective-C++ module

Turbo Native Modules on iOS are Objective-C++. This one implements the NativeGraffityARCloudSpec protocol generated from your spec and forwards calls to the Swift presenter.

ios/RCTGraffityARCloud.h
#import <Foundation/Foundation.h> #import <AppSpecs/AppSpecs.h> NS_ASSUME_NONNULL_BEGIN @interface RCTGraffityARCloud : NSObject <NativeGraffityARCloudSpec> @end NS_ASSUME_NONNULL_END
ios/RCTGraffityARCloud.mm
#import "RCTGraffityARCloud.h" #import <UIKit/UIKit.h> #import <React/RCTUtils.h> #import "YourApp-Swift.h" // Replace YourApp with your target's product module name. @implementation RCTGraffityARCloud + (NSString *)moduleName { return @"NativeGraffityARCloud"; } - (std::shared_ptr<facebook::react::TurboModule>)getTurboModule: (const facebook::react::ObjCTurboModule::InitParams &)params { return std::make_shared<facebook::react::NativeGraffityARCloudSpecJSI>(params); } - (void)open:(NSString *)accessToken resolve:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject { dispatch_async(dispatch_get_main_queue(), ^{ UIViewController *presenter = RCTPresentedViewController(); if (presenter == nil) { reject(@"NO_PRESENTER", @"No view controller is available.", nil); return; } [GraffityARPresenter.shared openWithAccessToken:accessToken presenter:presenter completion:^(NSError *_Nullable error) { if (error != nil) { reject(@"AR_OPEN_FAILED", error.localizedDescription, error); } else { resolve(nil); } }]; }); } - (void)close:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject { dispatch_async(dispatch_get_main_queue(), ^{ [GraffityARPresenter.shared closeWithCompletion:^{ resolve(nil); }]; }); } @end

The modulesProvider entry in package.json registers RCTGraffityARCloud, so RCT_EXPORT_MODULE is not needed.

Generate and build

cd ios && bundle exec pod install

Rerun pod install whenever the spec changes.

Android

Install the SDK

In android/, follow Install the SDK to add tech.graffity.android:arcloud:5.5.0, set minSdk = 28, and use JDK 17. Add the manifest permissions, ARCore metadata, and Activity declaration.

Add the AR host

Copy the complete GraffityARActivity host and layout into your app package. It creates the SDK, requests permissions, checks ARCore installation, and shuts down on Close, Back, or GraffityARActivity.closeActive().

Add the Kotlin module

Codegen generates NativeGraffityARCloudSpec in the javaPackageName you configured.

android/app/src/main/java/com/example/app/GraffityARCloudModule.kt
package com.example.app import android.content.Intent import com.facebook.react.bridge.Promise import com.facebook.react.bridge.ReactApplicationContext import com.facebook.react.bridge.UiThreadUtil class GraffityARCloudModule(reactContext: ReactApplicationContext) : NativeGraffityARCloudSpec(reactContext) { override fun getName(): String = NAME override fun open(accessToken: String, promise: Promise) { if (accessToken.isBlank()) { promise.reject("INVALID_TOKEN", "An access token is required.") return } UiThreadUtil.runOnUiThread { if (GraffityARActivity.isOpen) { promise.reject("AR_ALREADY_OPEN", "Close the current AR session first.") return@runOnUiThread } val activity = reactApplicationContext.currentActivity if (activity == null) { promise.reject("NO_ACTIVITY", "No Activity is available to present AR.") return@runOnUiThread } try { activity.startActivity( Intent(activity, GraffityARActivity::class.java) .putExtra(GraffityARActivity.EXTRA_ACCESS_TOKEN, accessToken) ) promise.resolve(null) } catch (error: Exception) { promise.reject("AR_OPEN_FAILED", error.message, error) } } } override fun close(promise: Promise) { UiThreadUtil.runOnUiThread { GraffityARActivity.closeActive() promise.resolve(null) } } companion object { const val NAME = "NativeGraffityARCloud" } }

Register the package

android/app/src/main/java/com/example/app/GraffityARCloudPackage.kt
package com.example.app import com.facebook.react.BaseReactPackage import com.facebook.react.bridge.NativeModule import com.facebook.react.bridge.ReactApplicationContext import com.facebook.react.module.model.ReactModuleInfo import com.facebook.react.module.model.ReactModuleInfoProvider class GraffityARCloudPackage : BaseReactPackage() { override fun getModule(name: String, reactContext: ReactApplicationContext): NativeModule? = if (name == GraffityARCloudModule.NAME) GraffityARCloudModule(reactContext) else null override fun getReactModuleInfoProvider() = ReactModuleInfoProvider { mapOf( GraffityARCloudModule.NAME to ReactModuleInfo( name = GraffityARCloudModule.NAME, className = GraffityARCloudModule.NAME, canOverrideExistingModule = false, needsEagerInit = false, isCxxModule = false, isTurboModule = true ) ) } }

Add the package to the package list in MainApplication.kt:

MainApplication.kt
PackageList(this).packages.apply { add(GraffityARCloudPackage()) }

Use from JavaScript

OpenARButton.tsx
import React from 'react'; import { Alert, Button } from 'react-native'; import GraffityARCloud from './specs/NativeGraffityARCloud'; export function OpenARButton({ accessToken }: { accessToken: string }) { const open = async () => { try { await GraffityARCloud.open(accessToken); } catch (error) { Alert.alert('Unable to open AR', (error as Error).message); } }; return <Button title="Open AR" onPress={open} />; } // GraffityARCloud.close() ends the session from code. // The native host also provides its own Close button.
ℹ️

The open promise resolves when the native host is presented (iOS) or launched (Android). It does not wait for permission approval, SDK initialization, or VPS localization.

Error codePlatformMeaning
INVALID_TOKENAndroidThe token is blank. iOS reports malformed tokens as AR_OPEN_FAILED.
AR_ALREADY_OPENAndroidA host is already open. iOS reports this as AR_OPEN_FAILED.
NO_PRESENTER / NO_ACTIVITYiOS / AndroidNo foreground screen is available to present from.
AR_OPEN_FAILEDBothSDK initialization or presentation failed; see the message.

If JavaScript needs runtime events such as localization or arrival, add an event emitter to the spec and forward callbacks from GraffityARCloudDelegate and GraffityARCloudListener.

Run on a device

Run with npx react-native run-ios --device or npx react-native run-android on a physical device. AR does not run in the iOS Simulator or Android Emulator. Grant camera and location access, then follow the on-screen guidance in a mapped venue.

Troubleshooting

  • AppSpecs/AppSpecs.h or NativeGraffityARCloudSpec not found: check codegenConfig in package.json, then rerun pod install (iOS) or rebuild (Android).
  • YourApp-Swift.h not found: use the target’s Product Module Name from Xcode build settings. It differs from the display name when the name contains spaces or dashes.
  • Xcode reports that node is not found: set the Node path for Xcode’s build scripts.
echo "export NODE_BINARY=$(command -v node)" > ios/.xcode.env.local
  • enum clockid_t or other header errors: make sure the project path has no spaces.
# DO /Users/JohnDoe/ReactProject/ArApp # DON'T /Users/John Doe/React Project/ArApp

Report issues through the issue center.