Skip to main content

Plugin integration

|

The Magic Lane Maps SDK for React Native is built on top of the TypeScript SDK, providing the same powerful mapping features with a native React Native component for rendering maps.

info

The React Native plugin shares nearly all functionality with the TypeScript SDK. The only distinction lies in how the map view is created and rendered, using the GLView component. Everything else - APIs, features, and functionality covered in the TypeScript SDK documentation - applies to React Native as well.

Installation​

Install both the core Maps SDK and the React Native adapter:

Using npm​

npm install @magiclane/maps-sdk @magiclane/maps-sdk-react-native

Using yarn​

yarn add @magiclane/maps-sdk @magiclane/maps-sdk-react-native

Using pnpm​

pnpm add @magiclane/maps-sdk @magiclane/maps-sdk-react-native

Get Your API Token​

To use the Maps SDK, you need an API token from Magic Lane.

  1. Visit the Magic Lane Developer Portal
  2. Sign up or log in to your account
  3. Create a new project or select an existing one
  4. Copy your API token from the project dashboard
important

Keep your API token secure! Never commit it directly to version control. Use environment variables or a secure configuration management solution.

Basic Setup​

Initialize the SDK​

Before creating the map view, you need to initialize the SDK with your API token:

import { 
  GemKitPlatform, 
  SdkSettings, 
  IGemKitPlatform 
} from '@magiclane/maps-sdk';
import { GemKitNativeReact } from '@magiclane/maps-sdk-react-native';

// Initialize the platform (do this once in your app)
let gemKitInstance;
if (IGemKitPlatform.getInstance() == null) {
  gemKitInstance = new GemKitNativeReact();
  GemKitPlatform.getInstance(gemKitInstance);
} else {
  gemKitInstance = IGemKitPlatform.getInstance();
}

// Load the native module and set authorization
GemKitPlatform.getInstance().loadNative();
SdkSettings.appAuthorization = "YOUR_API_TOKEN_HERE";
Platform-specific initialization

On Android, you may need to delay initialization slightly to ensure native modules are ready:

if (Platform.OS === 'android') {
  setTimeout(init, 2000);
} else {
  init();
}

Create the Map View​

The key difference in React Native is using the GLView component instead of creating a DOM element:

import { GLView } from '@magiclane/maps-sdk-react-native';

<GLView
  style={{ flex: 1 }}
  onMapReady={(event) => {
    if (event.gemMap) {
      // Map is ready - you can now interact with it
      const map = event.gemMap;
      console.log('Map initialized successfully!');
    }
  }}
/>
GLView Component

The GLView component is the React Native equivalent of the web SDK's map container. It handles all the native rendering and provides a gemMap instance through the onMapReady callback.

Component Props​

The GLView component accepts the following props:

PropTypeDescription
styleViewStyleReact Native style object for the view container
onMapReady(event: { gemMap: GemMap }) => voidCallback fired when the map is initialized and ready

Using the Rest of the SDK​

Once you have the gemMap instance from onMapReady, you can use all the features documented in the TypeScript SDK:

Complete Example​

See the React Native Hello World example for a complete, working implementation.

Platform Requirements​

iOS​

  • iOS 13.0 or higher
  • Xcode 14.0 or higher

Android​

  • Android API level 24 (Android 7.0) or higher
  • Android SDK 33 or higher

Next Steps​

Last updated on