Instant Games

Unity Plugin

Updated: Apr 15, 2026
Copy for LLM
The Meta Instant Games Unity Plugin provides a C# wrapper around the Facebook Instant Games SDK, enabling Unity WebGL games to access platform features without writing JavaScript. The plugin covers the full SDK surface area including player identity, social contexts, payments, tournaments, ads, matchmaking, and overlay views (NEZP). Under Zero Permissions, direct access to player names and photos is not available — the plugin uses overlay views to display this information securely through Meta-controlled iframes.

Features

  • Full FBInstant SDK coverage — Player identity, social contexts, payments, tournaments, ads, matchmaking, and more
  • Overlay Views (NEZP) — HTML/CSS layers rendered on top of the Unity WebGL canvas with templating, data binding, and custom events
  • Async/Await API — All SDK calls use C# Task-based async patterns
  • Editor mocking — API calls return mock data in the Unity Editor for testing without a browser
  • Editor tools — Built-in windows for bundle uploading, project optimization, and visual overlay view building
The plugin source code is available on GitHub: meta_instant_games_unity_plugin⁠.

Requirements

  • Unity 2022 or later
  • Unity WebGL build target

Project setup

  1. Download or clone the plugin from the GitHub repository⁠ and import it into your Unity project under Assets/Meta.InstantGames/.
  2. Open Window > Instant Games > Project Optimiser to apply recommended WebGL build settings:
    • Build target: WebGL
    • Compression: Disabled
    • WebGL template: PROJECT:FB
    • Run In Background: Enabled
    • Input Handling: Both
  3. Use the WebGL template at Assets/WebGLTemplates/FB/ which handles SDK initialization automatically.

Build your game

After importing the plugin and applying the recommended WebGL settings, build your game as a standard Unity WebGL project:
  1. Open File > Build Settings and select WebGL as the build target.
  2. Open Player Settings > Player > Resolution and Presentation and set WebGL Template as FB
  3. Ensure the correct scenes are added in the Scenes In Build field on Build Settings.
  4. Click Build and choose an output folder.
  5. When the build completes, verify the output contains index.html and the plugin’s generated Instant Games assets at the root of the bundle before zipping and uploading it to your app.

Basic usage

using Meta.InstantGames;

// Initialize the SDK
await FBInstant.InitializeAsync();
await FBInstant.StartGameAsync();

// Get player info
string playerId = await FBInstant.Player.GetID();
string playerName = await FBInstant.Player.GetName();

// Post a score
await FBInstant.PostSessionScore(100);
All API calls are async and return Task<string> or typed results. In the Unity Editor, calls return mock data after a short delay for testing purposes.

Core API

The plugin is organized around a singleton FBInstant entry point with sub-APIs accessed via static properties:
PropertyDescription
FBInstant.Player
Player identity, data storage, connected players
FBInstant.Context
Game context management (threads, groups)
FBInstant.Payment
In-app purchases and product catalog
FBInstant.Tournament
Tournament creation, joining, and scoring
FBInstant.Community
Official page/group follow and join
FBInstant.Room
Live match data
FBInstant.OverlayViews
Overlay view creation and management
Additional top-level methods on FBInstant cover lifecycle (InitializeAsync, StartGameAsync, Quit), platform info (GetLocale, GetPlatform), social actions (ShareAsync, InviteAsync, UpdateAsync), ads, matchmaking, analytics, and more.

Player data

Store and retrieve player data using the cloud storage API:
// Save player data
await FBInstant.Player.SetDataAsync("{\"level\": 5, \"coins\": 300}");

// Load player data
string data = await FBInstant.Player.GetDataAsync("[\"level\", \"coins\"]");

// Flush to ensure persistence
await FBInstant.Player.FlushDataAsync();

Social contexts

Manage the social context in which the game is being played:
// Get current context
string contextId = await FBInstant.Context.GetID();
string contextType = await FBInstant.Context.GetType();

// Switch to a different context
await FBInstant.Context.SwitchAsync("1234567890");

// Create a new context with a player
await FBInstant.Context.CreateAsync("playerID123");

// Get players in the current context
string players = await FBInstant.Context.GetPlayersAsync();

Ads

The plugin supports interstitial, rewarded video, and banner ad formats:
// Interstitial ads
string adInstance = await FBInstant.GetInterstitialAdAsync("PLACEMENT_ID");
await FBInstant.LoadAdAsync(adInstance);
await FBInstant.ShowAdAsync(adInstance);

// Rewarded video ads
string rewardedAd = await FBInstant.GetRewardedVideoAsync("PLACEMENT_ID");
await FBInstant.LoadAdAsync(rewardedAd);
await FBInstant.ShowAdAsync(rewardedAd);

// Banner ads
await FBInstant.LoadBannerAdAsync("PLACEMENT_ID");
await FBInstant.HideBannerAdAsync();

In-app purchases

Handle in-app purchases through the payments API:
// Get product catalog
string catalog = await FBInstant.Payment.GetCatalogAsync();

// Purchase a product
string purchase = await FBInstant.Payment.PurchaseAsync(
    "{\"productID\": \"gem_pack_100\"}"
);

// Consume a purchase
await FBInstant.Payment.ConsumePurchaseAsync("purchaseToken123");

// Get unconsumed purchases
string purchases = await FBInstant.Payment.GetPurchasesAsync();

Tournaments

Create, join, and manage tournaments:
// Post a score to the current tournament
await FBInstant.Tournament.PostScoreAsync(500);

// Create a new tournament
string tournament = await FBInstant.Tournament.CreateAsync(
    "{\"initialScore\": 100, \"config\": {\"title\": \"Weekly Challenge\"}}"
);

// Share the current tournament
await FBInstant.Tournament.ShareAsync("{\"score\": 500}");

// Get available tournaments
string tournaments = await FBInstant.Tournament.GetTournamentsAsync();

Overlay views (NEZP)

Overlay views are HTML/CSS layers rendered on top of the Unity WebGL canvas. They are defined using XML templates and support data binding, custom events, CSS styling, and profile integration.
// Create an overlay from an XML template
OverlayView view = await FBInstant.OverlayViews.CreateOverlayViewAsync(
    "ig_views/share.xml", "myOverlay", "", "ig_views/share.css", dataJson
);

// Show, update, and dismiss
await view.ShowAsync();
await view.UpdateAsync(newDataJson);
await view.DismissAsync();
The Overlay View Builder editor window (Window > Instant Games > Overlay View Builder) provides a visual drag-and-drop interface for creating overlay XML files.

Editor tools

ToolMenu pathDescription
Bundle Uploader
Window > Instant Games > Bundle Uploader
Build, zip, and upload WebGL bundles to the Instant Games platform
Project Optimiser
Window > Instant Games > Project Optimiser
Apply recommended WebGL build settings in one click
Overlay View Builder
Window > Instant Games > Overlay View Builder
Visual editor for creating overlay view XML files

Project structure

Assets/
  Meta.InstantGames/
    Editor/              Editor windows (Bundle Uploader, Overlay View Builder)
    Runtime/
      Plugins/           FBInstant API wrappers + JS interop files
        UtilClasses/     Data models, enums, payload types
      Scripts/           Bridge, JSON utilities, helper components
      Tests/             Runtime unit tests
  Demo/                  Example scenes and scripts
  WebGLTemplates/FB/     WebGL template with SDK bootstrap

Assemblies

AssemblyScopeDescription
Meta.InstantGames.Runtime
Editor + WebGL
Core runtime API
Meta.InstantGames.Editor
Editor only
Editor tools
Meta.InstantGames.Tests
Tests
Runtime unit tests
Meta.InstantGames.Editor.Tests
Tests
Editor unit tests

Next steps