@octopus-community/react-native

React Native module for the Octopus Community Android and Swift SDKs

• Installation
  • iOS setup
  • Compatibility table
• Usage
  • Initialization
  • Show the UI
  • API docs
  • Example app
• Troubleshooting

Installation

npm install @octopus-community/react-native

iOS setup

Make sure to use_frameworks in your Podfile.

# Podfile
linkage = :static # or :dynamic
if linkage != nil
  Pod::UI.puts "Configuring Pod with #{linkage}ally linked Frameworks".green
  use_frameworks! :linkage => linkage.to_sym
end

Due to a bug in XCode 15, you might need to set ENABLE_USER_SCRIPT_SANDBOXING to YES and then to NO in order to compile (see this issue).

Compatibility table

| React Native version(s) | Android | iOS | Old arch | New arch | Supporting version(s) | |-------------------------| ------- |-------| -------- | ------------- | --------------------- | | v0.78+ | 5.0+ | 14.0+ | ✅ | Interop layer | v1+ |

• Older React Native versions might be supported but were untested
• New arch is currently supported with the interoperability layer
• Other requirements for current version:
  • Android
    • Kotlin version 2
  • iOS
    • XCode 16.0+

Expo

Configure use_frameworks (static or dynamic) with expo-build-properties:

[
  "expo-build-properties",
  {
    "ios": {
      "useFrameworks": "static"
    }
  }
]

Usage

Initialization

Initialize the SDK with your API key with initialize.

Choose whether your app or Octopus handles user authentification:

Octopus-handled authentification

import { initialize } from '@octopus-community/react-native';

await initialize({
  apiKey: 'YOUR_OCTOPUS_API_KEY',
  connectionMode: { type: 'octopus' }
});

Single Sign-On (SSO)

For SSO mode:

• your app manages user authentication and certain profile fields. You specify which profile fields your app will handle directly
• you need to provide a token provider function that returns a valid JWT token for the authenticated user.
  • use the useUserTokenProvider hook in React components:

import {
  initialize,
  addEditUserListener,
  addLoginRequiredListener,
  connectUser,
  disconnectUser,
  useUserTokenProvider,
  closeUI,
} from '@octopus-community/react-native';

// Initialize with SSO mode and custom theme
await initialize({
  apiKey: 'YOUR_OCTOPUS_API_KEY',
  connectionMode: {
    type: 'sso',
    appManagedFields: ['username', 'profilePicture', 'biography']
  },
  theme: {
    colors: {
      primary: '#FF6B35', // Your brand's primary color
      primaryLowContrast: '#FF8C69', // Lighter variation
      primaryHighContrast: '#CC4A1A', // Darker variation
      onPrimary: '#FFFFFF', // Text color on primary background
    },
    logo: {
      image: Image.resolveAssetSource(require('./assets/images/logo.png')), // Your custom logo
    },
  }
});

// Listen for when authentication is required
const loginRequiredSubscription = addLoginRequiredListener(() => {
  // Navigate to your app's login screen
  console.log('User needs to log in');
  closeUI();
});

// Listen for when users want to edit their profile
const editUserSubscription = addEditUserListener(({ fieldToEdit }) => {
  // Navigate to your app's profile editing screen
  // for the specific field (username, profilePicture, etc.)
  console.log(`User wants to edit: ${fieldToEdit}`);
  closeUI();
});

// Set up token provider (in a React component)
useUserTokenProvider(async () => {
  const token = await refreshUserToken();
  return token;
});

// Connect a user after they log in
await connectUser({
  userId: 'unique-user-id',
  profile: {
    username: 'john_doe',
    profilePicture: 'https://example.com/avatar.jpg',
    biography: 'Software developer',
    legalAgeReached: true,
  },
});

// Disconnect the user when they log out
await disconnectUser();

// Cleanup listeners when appropriate (eg. in return of a useEffect)
loginRequiredSubscription.remove();
editUserSubscription.remove();

Show the UI

Show the Octopus home screen with the openUI() method.

Future versions of this React Native module will let you show the UI in your React components. Please reach out if you need this prioritized.

Theme Customization

The Octopus SDK provides comprehensive theming capabilities to match your app's branding. You can customize colors, fonts, and logo, with full support for both light and dark modes.

Basic Theme Setup

import { Image } from 'react-native';

await initialize({
  apiKey: 'YOUR_OCTOPUS_API_KEY',
  connectionMode: { type: 'octopus' },
  theme: {
    colors: {
      primary: '#FF6B35', // Main brand color
      primaryLowContrast: '#FF8C69', // Lighter variation of primary
      primaryHighContrast: '#CC4A1A', // Darker variation for high contrast
      onPrimary: '#FFFFFF', // Text color on primary background
    },
    logo: {
      image: Image.resolveAssetSource(require('./assets/images/logo.png')),
    },
  }
});

Dark/Light Mode Management

The SDK automatically handles system appearance changes, but you can also force specific modes:

System Mode (Default)

// The SDK automatically follows the system appearance
// No additional configuration needed
await initialize({
  apiKey: 'YOUR_OCTOPUS_API_KEY',
  connectionMode: { type: 'octopus' },
  theme: { /* your theme */ }
});

Forced Light Mode

import { Appearance } from 'react-native';

// Force light mode for your entire app
Appearance.setColorScheme('light');

await initialize({
  apiKey: 'YOUR_OCTOPUS_API_KEY',
  connectionMode: { type: 'octopus' },
  theme: { /* your theme */ }
});

Forced Dark Mode

import { Appearance } from 'react-native';

// Force dark mode for your entire app
Appearance.setColorScheme('dark');

await initialize({
  apiKey: 'YOUR_OCTOPUS_API_KEY',
  connectionMode: { type: 'octopus' },
  theme: { /* your theme */ }
});

Dual-Mode Color Themes

For enhanced theming, you can provide separate color sets for light and dark modes:

await initialize({
  apiKey: 'YOUR_OCTOPUS_API_KEY',
  connectionMode: { type: 'octopus' },
  theme: {
    colors: {
      light: {
        primary: '#3B82F6', // Blue for light mode
        primaryLowContrast: '#60A5FA',
        primaryHighContrast: '#1D4ED8',
        onPrimary: '#FFFFFF',
      },
      dark: {
        primary: '#60A5FA', // Lighter blue for dark mode
        primaryLowContrast: '#93C5FD',
        primaryHighContrast: '#3B82F6',
        onPrimary: '#000000',
      },
    },
  }
});

Font Customization

Customize typography with text styles and font sizes:

await initialize({
  apiKey: 'YOUR_OCTOPUS_API_KEY',
  connectionMode: { type: 'octopus' },
  theme: {
    fonts: {
      textStyles: {
        title1: {
          fontType: 'serif', // serif, monospace, or default
          fontSize: { size: 28 }
        },
        title2: {
          fontType: 'serif',
          fontSize: { size: 22 }
        },
        body1: {
          fontType: 'default', // Uses system default
          fontSize: { size: 16 }
        },
        body2: {
          fontSize: { size: 14 } // Only size, uses default font type
        },
        caption1: {
          fontType: 'monospace',
          fontSize: { size: 12 }
        },
        caption2: {
          fontSize: { size: 10 }
        },
      }
    }
  }
});

Theme Application

Themes are applied when the Octopus UI is opened. The SDK automatically detects the current system appearance (light/dark mode) and applies the appropriate theme configuration.

Complete Theme Example

Here's a comprehensive example showing all theming options:

import { Image, Appearance } from 'react-native';
import { initialize } from '@octopus-community/react-native';

// Force dark mode (optional)
Appearance.setColorScheme('dark');

await initialize({
  apiKey: 'YOUR_OCTOPUS_API_KEY',
  connectionMode: {
    type: 'sso',
    appManagedFields: ['username', 'profilePicture']
  },
  theme: {
    // Dual-mode colors
    colors: {
      light: {
        primary: '#8B5CF6',
        primaryLowContrast: '#A78BFA',
        primaryHighContrast: '#7C3AED',
        onPrimary: '#FFFFFF',
      },
      dark: {
        primary: '#A78BFA',
        primaryLowContrast: '#C4B5FD',
        primaryHighContrast: '#8B5CF6',
        onPrimary: '#000000',
      },
    },
    // Custom fonts
    fonts: {
      textStyles: {
        title1: { fontType: 'serif', fontSize: { size: 28 } },
        title2: { fontType: 'serif', fontSize: { size: 22 } },
        body1: { fontSize: { size: 16 } },
        body2: { fontSize: { size: 14 } },
        caption1: { fontType: 'monospace', fontSize: { size: 12 } },
        caption2: { fontSize: { size: 10 } },
      }
    },
    // Custom logo
    logo: {
      image: Image.resolveAssetSource(require('./assets/images/logo.png')),
    },
  }
});

Dynamic Theme Switching

To change themes in your app, you need to re-initialize the SDK with the new theme configuration:

// Example: Switch between different theme sets
const switchToGreenTheme = async () => {
  await initialize({
    apiKey: 'YOUR_OCTOPUS_API_KEY',
    connectionMode: { type: 'sso', appManagedFields: ['username'] },
    theme: {
      colors: {
        light: {
          primary: '#10B981',
          primaryLowContrast: '#34D399',
          primaryHighContrast: '#059669',
          onPrimary: '#FFFFFF',
        },
        dark: {
          primary: '#34D399',
          primaryLowContrast: '#6EE7B7',
          primaryHighContrast: '#10B981',
          onPrimary: '#000000',
        },
      }
    }
  });
};

Theme Configuration Reference

Color Properties:

• primary: Main brand color (hex format: #FF6B35 or FF6B35)
• primaryLowContrast: Lighter variation for subtle elements
• primaryHighContrast: Darker variation for high contrast needs
• onPrimary: Text color displayed over primary background

Font Types:

• default: System default font
• serif: Serif font family
• monospace: Monospace font family

Text Styles:

• title1: Large titles (default: 28pt)
• title2: Medium titles (default: 22pt)
• body1: Primary body text (default: 16pt)
• body2: Secondary body text (default: 14pt)
• caption1: Small captions (default: 12pt)
• caption2: Extra small captions (default: 10pt)

Supported Formats:

• Colors: 3-digit (#F63), 6-digit (#FF6633), 8-digit (#FF6633FF) hex codes
• Images: Use Image.resolveAssetSource(require('./path/to/image.png')) for bundled assets
• Fonts: Choose between serif, monospace, or default font types

Platform Behavior:

• iOS: Uses adaptive colors that automatically respond to system appearance changes
• Android: Theme is applied when the UI opens and reflects the current system appearance
• Theme Changes: Require re-initializing the SDK with new theme configuration
• System Mode: Automatically follows device light/dark mode settings
• Forced Mode: Use Appearance.setColorScheme('light'|'dark') to override system settings

Note: All theme properties are optional. If not provided, the default Octopus theme will be used.

For more detailed theming information and advanced customization options, see the Octopus Community iOS SDK theming documentation.

API docs

For details about the Typescript API, head to the API docs.

Key Theming Functions

• initialize(params): Initialize the SDK with theme configuration
• Appearance.setColorScheme(mode): Force light/dark mode (React Native API)
• openUI(): Open the Octopus UI with the current theme applied

Example app

Take a look at our example app which demonstrates:

• Complete theming system with multiple color themes and font customizations
• Dark/Light mode management with system detection and forced modes
• Dual-mode color themes with separate light and dark color sets
• Font customization with different font types (serif, monospace, default) and sizes
• Theme switching by re-initializing the SDK with new configurations
• Logo customization with bundled image assets
• Interactive theme controls to test different configurations

The example app includes a comprehensive theme selector interface that lets you:

• Switch between system, light, and dark modes
• Choose from multiple pre-defined color themes (Theme 1, 2, 3, or None)
• Customize font types (default, serif, monospace) and sizes (small, default, large)
• Toggle custom logo display
• See theme changes applied when the UI reopens

This is the perfect starting point to understand how to implement theming in your own React Native app.

Troubleshooting

Any error that might be intercepted by the React Native module will be rejected in the methods you call. If it cannot be intercepted, you may see the underlying SDK's logs in your native logs.

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.