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
| Layer | File | Role |
|---|---|---|
| JavaScript | specs/NativeGraffityARCloud.ts | Typed spec; Codegen generates the native interfaces from it. |
| iOS | GraffityARPresenter.swift + RCTGraffityARCloud.mm | Swift presenter for ARExperienceViewController, wrapped by an Objective-C++ module. |
| Android | GraffityARCloudModule.kt + GraffityARCloudPackage.kt | Kotlin module that launches GraffityARActivity. |
Define the module spec
Create the spec
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.
{
"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.
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.
#import <Foundation/Foundation.h>
#import <AppSpecs/AppSpecs.h>
NS_ASSUME_NONNULL_BEGIN
@interface RCTGraffityARCloud : NSObject <NativeGraffityARCloudSpec>
@end
NS_ASSUME_NONNULL_END#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);
}];
});
}
@endThe modulesProvider entry in package.json registers RCTGraffityARCloud, so RCT_EXPORT_MODULE is not needed.
Generate and build
cd ios && bundle exec pod installRerun 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.
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
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:
PackageList(this).packages.apply {
add(GraffityARCloudPackage())
}Use from JavaScript
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 code | Platform | Meaning |
|---|---|---|
INVALID_TOKEN | Android | The token is blank. iOS reports malformed tokens as AR_OPEN_FAILED. |
AR_ALREADY_OPEN | Android | A host is already open. iOS reports this as AR_OPEN_FAILED. |
NO_PRESENTER / NO_ACTIVITY | iOS / Android | No foreground screen is available to present from. |
AR_OPEN_FAILED | Both | SDK 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.horNativeGraffityARCloudSpecnot found: checkcodegenConfiginpackage.json, then rerunpod install(iOS) or rebuild (Android).YourApp-Swift.hnot 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
nodeis not found: set the Node path for Xcode’s build scripts.
echo "export NODE_BINARY=$(command -v node)" > ios/.xcode.env.localenum clockid_tor other header errors: make sure the project path has no spaces.
# DO
/Users/JohnDoe/ReactProject/ArApp
# DON'T
/Users/John Doe/React Project/ArAppReport issues through the issue center.