Skip to main content

Hello World

|

This example demonstrates the simplest way to display a map in a React Native application.

Overview​

This example shows:

  • How to initialize the SDK in React Native
  • How to create a map view using the GLView component
  • Platform-specific initialization handling
  • Basic map lifecycle management

Key Differences from Web​

The React Native SDK shares 99% of the Maps SDK for TypeScript functionality. The only difference is how you create the map view:

  • Web: Use gemKit.createView() to create a DOM element
  • React Native: Use the GLView component

All other APIs (search, routing, navigation, etc.) work identically.

Complete Code​

import React, { useEffect, useState } from 'react';
import { View, Text, StyleSheet, Platform, StatusBar, SafeAreaView } from 'react-native';
import {
  GemKitPlatform,
  SdkSettings,
  IGemKitPlatform,
} from '@magiclane/maps-sdk';
import { GemKitNativeReact } from '@magiclane/maps-sdk-react-native';
import { GLView } from '@magiclane/maps-sdk-react-native';

export default function HelloWorldDemo() {
  const [initialized, setInitialized] = useState(false);
  const [initError, setInitError] = useState<string | null>(null);
  const [gemMap, setGemMap] = useState<any>(null);
  const [status, setStatus] = useState('Initializing...');

  useEffect(() => {
    let mounted = true;

    // Initialize GemKit platform
    let gemKitInstance;
    if (IGemKitPlatform.getInstance() == null) {
      gemKitInstance = new GemKitNativeReact();
      GemKitPlatform.getInstance(gemKitInstance);
    } else {
      gemKitInstance = IGemKitPlatform.getInstance();
    }

    const init = async () => {
      try {
        // Load the native module
        GemKitPlatform.getInstance().loadNative();
        
        // Set your API token
        SdkSettings.appAuthorization = "YOUR_API_TOKEN_HERE";
        
        if (!mounted) return;
        
        setInitialized(true);
        setStatus('SDK initialized');
      } catch (e: any) {
        setInitError(String(e?.message || e));
        setStatus('Initialization failed');
      }
    };

    // Android needs a slight delay to ensure native modules are ready
    if (Platform.OS === 'android') {
      setTimeout(init, 2000);
    } else {
      init();
    }

    return () => {
      mounted = false;
    };
  }, []);

  return (
    <SafeAreaView style={styles.safeArea}>
      <StatusBar barStyle="light-content" backgroundColor="#000" />
      <View style={styles.container}>
        {/* The GLView component renders the map */}
        <GLView
          style={{ flex: 1, backgroundColor: '#e8e8e8' }}
          onMapReady={(event) => {
            if (event.gemMap) {
              // Map is ready - store reference for later use
              setGemMap(event.gemMap);
              setStatus('Map Ready');
            }
          }}
        />
        
        {/* Overlay with status information */}
        <View style={styles.overlay}>
          <Text style={styles.header}>Hello World</Text>
          {!initialized && !initError && (
            <Text style={styles.info}>Initializing...</Text>
          )}
          {initError && (
            <Text style={styles.error}>Init failed: {initError}</Text>
          )}
          {status ? <Text style={styles.status}>{status}</Text> : null}
        </View>
      </View>
    </SafeAreaView>
  );
}

const styles = StyleSheet.create({
  safeArea: {
    flex: 1,
    backgroundColor: '#000',
  },
  container: {
    flex: 1,
    backgroundColor: '#f0f0f0',
  },
  overlay: {
    position: 'absolute',
    top: Platform.OS === 'android' ? (StatusBar.currentHeight || 0) + 20 : 20,
    left: 12,
    right: 12,
    backgroundColor: '#fff',
    borderRadius: 12,
    padding: 16,
    shadowColor: '#000',
    shadowOpacity: 0.15,
    shadowRadius: 8,
    elevation: 5,
    zIndex: 1000,
    alignItems: 'center',
  },
  header: {
    fontSize: 16,
    fontWeight: '600',
    marginBottom: 8,
    textAlign: 'center',
    color: '#333',
  },
  info: {
    color: '#666',
    marginBottom: 8,
    textAlign: 'center',
    fontSize: 14,
  },
  error: {
    color: '#e74c3c',
    marginBottom: 8,
    textAlign: 'center',
    fontSize: 14,
  },
  status: {
    marginTop: 8,
    color: '#333',
    textAlign: 'center',
    fontSize: 12,
  },
});

Code Breakdown​

1. Initialization (Lines 17-56)​

The initialization process has three key steps:

  1. Create GemKit Platform Instance (Lines 22-27): Initialize the React Native platform adapter
  2. Load Native Module (Line 37): Connect to the native iOS/Android SDK
  3. Set Authorization (Line 40): Provide your API token
Platform-specific Timing

Android requires a small delay (2 seconds) to ensure native modules are fully loaded before initialization.

2. Map View Component (Lines 62-71)​

The GLView component is the React Native equivalent of a web map container:

<GLView
  style={{ flex: 1 }}
  onMapReady={(event) => {
    // Access the GemMap instance here
    const map = event.gemMap;
  }}
/>

3. Map Ready Callback (Lines 64-69)​

The onMapReady callback provides access to the GemMap instance. Once you have this reference, you can:

  • Center the map on a location
  • Add markers and overlays
  • Calculate routes
  • Start navigation
  • Use any other SDK features

What's Next?​

Now that you have a basic map working, you can:

  1. Add Map Interactions: Learn about map gestures
  2. Search for Places: Implement search functionality
  3. Calculate Routes: Add routing capabilities
  4. Add Navigation: Implement turn-by-turn navigation

Notes​

  • Remember to replace "YOUR_API_TOKEN_HERE" with your actual Magic Lane API token
  • Store sensitive tokens in environment variables or secure storage, not in source code
  • The gemMap instance from onMapReady gives you access to all SDK features
  • All examples and guides in this documentation (except view creation) apply to React Native
Last updated on