React SDK (@simula/ads) for integrating native advertising and mini-game components into AI character apps.

image.png

Quick Start

1. Install

npm install @simula/ads

2. Provider Setup

Wrap your application with SimulaProvider to initialize the SDK:

import { SimulaProvider } from '@simula/ads';

function App() {
  return (
    <SimulaProvider
      apiKey="SIMULA_xxx" // Your API key
      primaryUserID="xxxxx" // Optional: Hashed publisher provided user ID, highly recommended for better ad targeting
      hasPrivacyConsent={true} // Optional: Privacy consent flag. When false, suppresses collection of PII
      devMode={false} // Optional: Determines whether session is in dev mode or not
    >
      {/* Your application */}
    </SimulaProvider>
  );
}

3. Component Integration

Add components where you want games to appear.

MiniGameMenu

Modal component for displaying and launching sponsored mini-games. Clicking on a sponsored mini game opens an iframe that allows for a playable game.

image.png

Basic Usage

Prop Type Required Default Description
isOpen boolean Yes - Controls modal visibility
onClose () => void Yes - Menu close event handler
onGameOpen () => void No - Called when game is launched
onGameClose () => void No - Called when game and ad screen is closed
charName string Yes - Character name displayed in header
charID string Yes - Character identifier
charImage string Yes - Character avatar URL
messages Message[] No [] Conversation history for context
charDesc string No - Character description
maxGamesToShow `3 6 9` No
theme MiniGameTheme No {} Theme configuration
delegateChar boolean No true Whether Character displays the messages inside of the Simula provided frame
navigationType string No "dot" Navigation style for browsing game cards. "dot" shows dot indicators, "arrow" adds left/right arrow buttons, "pagination" shows page numbers. 
import { useState } from 'react';
import { MiniGameMenu } from '@simula/ads';

function ChatInterface() {
  const [menuOpen, setMenuOpen] = useState(false);

  return (
    <div>
      <button onClick={() => setMenuOpen(true)}>
        Play Games
      </button>
      <MiniGameMenu
        isOpen={menuOpen}
        onClose={() => setMenuOpen(false)}
        charName="Luna"
        charID="luna-123"
        charImage="<https://cdn.example.com/avatars/luna.png>"
      />
    </div>
  );
}

Props

interface MiniGameTheme {
  backgroundColor?: string;
  headerColor?: string;
  borderColor?: string;
  titleFont?: string;
  secondaryFont?: string;
  titleFontColor?: string;
  secondaryFontColor?: string;
  iconCornerRadius?: number;
  accentColor?: string;
  playableHeight?: number | string;
  playableBorderColor?: string;
}

Backend integration