RewardedMiniGame

Gates an in-app reward after playing a game with a given character. The user plays for minPlayThreshold seconds, plays a brief ad, then taps Claim Reward.

Basic Usage

import { useEffect, useRef, useState } from 'react';
import { SimulaRewardedMiniGame, SimulaEventType } from '@simula/ads-react-native';

function MessageLimitGate() {
  const [loaded, setLoaded] = useState(false);
  const retryAttempt = useRef(0);
  const rewardedGame = useRef(null);

  useEffect(() => {
    rewardedGame.current = SimulaRewardedMiniGame.init({
      adUnitId: 'simula-xxxx-rewarded', // Optional: provided by Simula for tracking and measurement
    });

    const subs = [
      rewardedGame.current.addAdEventListener(SimulaEventType.LOADED, () => {
        retryAttempt.current = 0;
        setLoaded(true);
      }),
      rewardedGame.current.addAdEventListener(SimulaEventType.LOAD_FAILED, () => {
        retryAttempt.current += 1;
        if (retryAttempt.current > 6) return;
        const delay = Math.pow(2, retryAttempt.current);
        setTimeout(() => rewardedGame.current.load(), delay * 1000);
      }),
      rewardedGame.current.addAdEventListener(SimulaEventType.EARNED_REWARD, () => {
        grantMessageCredits(10); // Only grant the reward here
      }),
      rewardedGame.current.addAdEventListener(SimulaEventType.REWARD_VERIFICATION_FAILED, () => {
        showError("Reward verification failed. Please try again.");
      }),
      rewardedGame.current.addAdEventListener(SimulaEventType.CLOSED, () => {
        setLoaded(false);
        rewardedGame.current.load();
      }),
    ];

    rewardedGame.current.load();

    return () => subs.forEach(sub => sub.remove());
  }, []);

  return (
    <button disabled={!loaded} onClick={() => rewardedGame.current.show({
      charID: 'luna-123', // Optional: current character, CharacterSelector pick, or omit for Simula default
      charName: 'Luna',
      charImage: 'https://cdn.example.com/avatars/luna.png',
    })}>
      Watch an ad to earn 10 message credits
    </button>
  );
}

Init Config

Parameter	Type	Required	Default	Description
adUnitId	string	No	—	Ad unit ID provided by Simula. Used for measurement and improved targeting.
minPlayThreshold	number	No	30	Minimum play time in seconds before Claim Reward appears. Clamped to [10, 30].

Show Config

The character info personalizes the game experience — the AI companion reacts to gameplay, sends messages, and is present throughout. Pass in the character the user is currently talking to, a character from CharacterSelector, or omit to use a Simula default.

Parameter	Type	Required	Description
charID	string	No	Character identifier
charName	string	No	Character name displayed in header
charImage	string	No	Character avatar URL
charDesc	string	No	Character description

Event Types

Event	Payload	Description
SimulaEventType.LOADED	—	Ad loaded and ready to show
SimulaEventType.LOAD_FAILED	errorInfo	Ad failed to load. Retry with exponential backoff.
SimulaEventType.DISPLAYED	adInfo	Ad displayed on screen
SimulaEventType.DISPLAY_FAILED	errorInfo	Ad failed to display. Load next ad.
SimulaEventType.CLICKED	adInfo	User tapped the ad
SimulaEventType.EARNED_REWARD	—	SSV succeeded. Grant the reward here — only trusted signal.
SimulaEventType.REWARD_VERIFICATION_FAILED	—	SSV failed. Show error, do not grant reward.
SimulaEventType.CLOSED	adInfo	User closed the ad. Load next ad.

Grant rewards only on EARNED_REWARD

Always grant the reward inside EARNED_REWARD — it is the only trusted signal. Re-call .load() after CLOSED or DISPLAY_FAILED.