SDK Documentation

Integrate the Fluby SDK into your game to enable ads, leaderboards, achievements, and cloud saves.

Contents

1. Getting Started

The Fluby SDK is a lightweight JavaScript library that lets your game communicate with the Fluby platform. Add the SDK script tag to your game's HTML file to get started.

HTML Add to <head> 
<script src="https://sdk.fluby.com/v1/fluby-sdk.min.js"></script>

You will also need your API key, which can be found on the API Keys page. The SDK is approximately 15KB gzipped and has no external dependencies.

2. Initialization

Initialize the SDK as early as possible in your game's startup sequence. The init() method returns a Promise that resolves when the SDK is ready.

JavaScript 
const sdk = FlubySDK.init({
  apiKey: 'YOUR_API_KEY',
  gameId: 'your-game-slug',
  debug: false,       // Enable console logging
  autoAds: true,      // Auto-show interstitials between levels
});

sdk.then(function() {
  console.log('Fluby SDK ready!');
  // Start your game here
  startGame();
}).catch(function(err) {
  console.error('SDK init failed:', err);
  // Game can still run without SDK
  startGame();
});
Tip: Always handle the SDK initialization failure gracefully. Your game should still be playable even if the SDK fails to load (e.g., when ad-blockers are active).

3. Ads Integration

The SDK supports two ad formats: interstitial ads (shown between levels or during transitions) and rewarded video ads (players opt-in for in-game rewards).

Interstitial Ads

JavaScript 
// Show an interstitial ad (e.g., between levels)
FlubySDK.ads.showInterstitial({
  onStart: function() {
    // Pause game audio/animations
    pauseGame();
  },
  onComplete: function() {
    // Resume game
    resumeGame();
  },
  onError: function(err) {
    // No ad available, continue game
    resumeGame();
  }
});

Rewarded Video Ads

JavaScript 
// Show a rewarded video (e.g., extra lives, bonus coins)
FlubySDK.ads.showRewarded({
  onStart: function() {
    pauseGame();
  },
  onRewarded: function() {
    // Player watched the full ad - grant reward
    giveExtraLife();
    resumeGame();
  },
  onSkipped: function() {
    // Player skipped - no reward
    resumeGame();
  },
  onError: function(err) {
    resumeGame();
  }
});
Best practice: Show interstitial ads at natural break points (level transitions, game over screens). Do not show ads during active gameplay. Limit interstitials to one every 3 minutes maximum.

4. Leaderboards

Add competitive leaderboards to increase player engagement and retention. You can create multiple leaderboards per game (e.g., high score, fastest time, highest level).

JavaScript 
// Submit a score
FlubySDK.leaderboard.submitScore({
  board: 'high-score',
  score: 15000,
  metadata: { level: 12, character: 'warrior' }
}).then(function(result) {
  console.log('Rank:', result.rank);
  console.log('Is new best:', result.isNewBest);
});

// Get top scores
FlubySDK.leaderboard.getScores({
  board: 'high-score',
  limit: 10,
  period: 'all-time'  // 'daily', 'weekly', 'monthly', 'all-time'
}).then(function(scores) {
  scores.forEach(function(entry) {
    console.log(entry.rank, entry.playerName, entry.score);
  });
});

5. Achievements

Define achievements in your developer dashboard, then unlock them in-game using the SDK. Achievements are displayed on the player's profile and on your game's page.

JavaScript 
// Unlock an achievement
FlubySDK.achievements.unlock('first-victory')
  .then(function(achievement) {
    console.log('Unlocked:', achievement.name);
    // SDK auto-shows a toast notification to the player
  });

// Update progress on a multi-step achievement
FlubySDK.achievements.setProgress('collect-100-coins', {
  current: 47,
  target: 100
});

// Get all achievements for this game
FlubySDK.achievements.getAll()
  .then(function(list) {
    list.forEach(function(a) {
      console.log(a.id, a.name, a.unlocked);
    });
  });

6. Cloud Saves

Let players save their progress to the cloud so they can continue on any device. Each player gets up to 1MB of save data per game. Save data is stored as JSON.

JavaScript 
// Save game data
FlubySDK.cloudSave.save({
  slot: 'autosave',
  data: {
    level: 12,
    score: 15000,
    inventory: ['sword', 'shield', 'potion'],
    settings: { music: true, sfx: true }
  }
}).then(function() {
  console.log('Game saved!');
});

// Load game data
FlubySDK.cloudSave.load('autosave')
  .then(function(saveData) {
    if (saveData) {
      loadLevel(saveData.level);
      setScore(saveData.score);
    } else {
      // No save found, start new game
      startNewGame();
    }
  });

// List all save slots
FlubySDK.cloudSave.list()
  .then(function(slots) {
    slots.forEach(function(s) {
      console.log(s.slot, s.updatedAt, s.size);
    });
  });

// Delete a save slot
FlubySDK.cloudSave.delete('autosave');
Note: Cloud saves require the player to be logged into their Fluby account. If the player is not logged in, save/load operations will fall back to localStorage automatically.

Need Help?

Have questions about the SDK or need assistance with integration?

Contact Support Get API Keys