Klujo React Native SDK

Integrate Klujo Games into your React Native mobile applications. This SDK provides components for displaying interactive word games and a rewards system to engage your users.

Table of Contents

• Compatibility
• Installation
• Getting Started
• SDK Initialization
• Player Authentication
• Components
  • KlujoGame
  • KlujoRewards
• Complete Example
• TypeScript Support
• Support
• License

Compatibility

| Platform / Technology | Version | Notes | | --------------------- | ------------- | ----------------------------------- | | React Native | >= 0.64.0 | Supports New Architecture | | React | >= 17.0.0 | Hooks required | | Expo | SDK 48+ | Works in managed and bare workflows | | iOS | 13.0+ | Requires WebView support | | Android | API 21+ (5.0) | Requires WebView support | | TypeScript | >= 4.0 | Full type definitions included | | Node.js | >= 18.0.0 | For development |

Expo Compatibility

This SDK is fully compatible with Expo projects:

• Managed workflow: Works out of the box with expo install
• Bare workflow: Works with standard npm/yarn installation
• Expo Go: Supported (requires compatible peer dependencies)

Installation

Install the SDK using npm or yarn:

npm install @klujo/klujo-react-native

yarn add @klujo/klujo-react-native

Required Peer Dependencies

This SDK requires the following peer dependencies:

npm install @react-native-async-storage/async-storage react-native-webview

yarn add @react-native-async-storage/async-storage react-native-webview

For Expo projects:

npx expo install @react-native-async-storage/async-storage react-native-webview

iOS Setup

For bare React Native projects, install the native dependencies:

cd ios && pod install

Getting Started

Before using any SDK functionality, you need:

• API Key: Your authentication key for the Klujo platform

You can obtain your API key from your Klujo Dashboard.

SDK Initialization

Initialize the SDK before using any components or methods. This should be done once when your app starts, typically in your root component or app initialization logic.

import { KlujoSDK } from '@klujo/klujo-react-native';

// Basic initialization
const playerUUID = await KlujoSDK.initialization('YOUR_API_KEY');

// With all options
const playerUUID = await KlujoSDK.initialization(
  'YOUR_API_KEY',      // apiKey (required)
  'existing-uuid',     // playerUUID (optional) - use existing player
  'your-internal-id',  // externalId (optional) - your system's user ID
  'production'         // environment (optional) - 'production' | 'development'
);

Parameters

| Parameter | Type | Required | Description | | ------------- | ------------------------------- | -------- | ----------------------------------------- | | apiKey | string | Yes | Your Klujo API key | | playerUUID | string | No | Existing player UUID to restore session | | externalId | string | No | Your internal user identifier | | environment | 'production' \| 'development' | No | API environment (default: 'production') |

Returns

Returns a Promise<string> that resolves with the player's UUID. Store this UUID to restore player sessions in future app launches.

Player Authentication

After initialization, you can optionally authenticate the player with their profile information. This links the anonymous player session to a user identity.

import { KlujoSDK } from '@klujo/klujo-react-native';

const playerUUID = await KlujoSDK.authentication({
  email: '[email protected]',
  full_name: 'John Doe',
});

Parameters

| Parameter | Type | Required | Description | | ----------- | -------- | -------- | ---------------------- | | email | string | No | Player's email address | | full_name | string | No | Player's full name |

Note: At least one parameter should be provided for meaningful authentication.

Returns

Returns a Promise<string> that resolves with the player's UUID.

Components

KlujoGame

A full-screen component that displays Klujo games in a WebView.

import { KlujoGame } from '@klujo/klujo-react-native';

// Basic usage
<KlujoGame />

// With custom styling and loading indicator
<KlujoGame
  style={{ flex: 1 }}
  showLoading={true}
  showRewards={true}
/>

Props

| Prop | Type | Default | Description | | ------------- | ----------- | ----------- | --------------------------------------- | | style | ViewStyle | undefined | Custom styles for the container | | showLoading | boolean | true | Show loading indicator while game loads | | showRewards | boolean | false | Show rewards interface within the game |

Example

import React from 'react';
import { View, StyleSheet } from 'react-native';
import { KlujoGame } from '@klujo/klujo-react-native';

const GameScreen = () => {
  return (
    <View style={styles.container}>
      <KlujoGame style={styles.game} showLoading={true} />
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
  game: {
    flex: 1,
  },
});

KlujoRewards

A floating action button that opens a modal displaying the player's rewards. The button appearance is customizable from your Klujo Dashboard.

import { KlujoRewards } from '@klujo/klujo-react-native';

// Basic usage (bottom-left, compressed)
<KlujoRewards />

// Custom position and expanded state
<KlujoRewards
  position="bottom-right"
  compressed={false}
/>

Props

| Prop | Type | Default | Description | | ------------ | -------------------------------------------------------------- | --------------- | ----------------------------------------------------------------- | | position | 'bottom-left' \| 'bottom-right' \| 'top-left' \| 'top-right' | 'bottom-left' | Position of the floating button | | compressed | boolean | true | Initial state - true shows only icon, false shows icon + text |

Positions

• bottom-left: Fixed to bottom-left corner
• bottom-right: Fixed to bottom-right corner
• top-left: Fixed to top-left corner
• top-right: Fixed to top-right corner

Example

import React from 'react';
import { View, StyleSheet } from 'react-native';
import { KlujoRewards } from '@klujo/klujo-react-native';

const HomeScreen = () => {
  return (
    <View style={styles.container}>
      {/* Your app content */}

      {/* Floating rewards button */}
      <KlujoRewards position="bottom-right" compressed={true} />
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
});

Complete Example

Here's a complete example showing SDK initialization, authentication, and component usage:

import React, { useEffect, useState } from 'react';
import { View, Text, Button, StyleSheet, ActivityIndicator } from 'react-native';
import { KlujoSDK, KlujoGame, KlujoRewards } from '@klujo/klujo-react-native';

const App = () => {
  const [isInitialized, setIsInitialized] = useState(false);
  const [showGame, setShowGame] = useState(false);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    initializeKlujo();
  }, []);

  const initializeKlujo = async () => {
    try {
      // Initialize the SDK
      const playerUUID = await KlujoSDK.initialization(
        'YOUR_API_KEY',
        undefined,           // Let SDK generate new UUID
        'user-123',          // Your internal user ID
        'production'
      );

      console.log('Player UUID:', playerUUID);

      // Optionally authenticate with user profile
      await KlujoSDK.authentication({
        email: '[email protected]',
        full_name: 'John Doe',
      });

      setIsInitialized(true);
    } catch (err) {
      setError('Failed to initialize Klujo SDK');
      console.error(err);
    }
  };

  if (error) {
    return (
      <View style={styles.centered}>
        <Text style={styles.error}>{error}</Text>
      </View>
    );
  }

  if (!isInitialized) {
    return (
      <View style={styles.centered}>
        <ActivityIndicator size="large" />
        <Text>Initializing...</Text>
      </View>
    );
  }

  if (showGame) {
    return (
      <View style={styles.container}>
        <KlujoGame style={styles.game} />
        <Button title="Back" onPress={() => setShowGame(false)} />
      </View>
    );
  }

  return (
    <View style={styles.container}>
      <View style={styles.content}>
        <Text style={styles.title}>Welcome to Klujo!</Text>
        <Button title="Play Game" onPress={() => setShowGame(true)} />
      </View>

      {/* Floating rewards button */}
      <KlujoRewards position="bottom-right" />
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
  centered: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
  },
  content: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
    padding: 20,
  },
  title: {
    fontSize: 24,
    fontWeight: 'bold',
    marginBottom: 20,
  },
  game: {
    flex: 1,
  },
  error: {
    color: 'red',
    fontSize: 16,
  },
});

export default App;

TypeScript Support

This SDK is written in TypeScript and includes full type definitions. All exports include their corresponding types:

import {
  KlujoSDK,
  KlujoGame,
  KlujoRewards,
  // Types
  type KlujoGameProps,
  type KlujoRewardsProps,
} from '@klujo/klujo-react-native';

Available Types

// KlujoGame component props
interface KlujoGameProps {
  style?: ViewStyle;
  showLoading?: boolean;
  showRewards?: boolean;
}

// KlujoRewards component props
interface KlujoRewardsProps {
  position?: 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right';
  compressed?: boolean;
}

Support

For questions, issues, or feature requests:

• Email: [email protected]
• Issues: Bitbucket Issues

License

This SDK is proprietary software. Unauthorized use, copying, modification, or distribution is strictly prohibited without prior written consent from Klujo.

For licensing inquiries, contact [email protected].

Made with care by the Klujo Team