meta-instant-games-unity-plugin

Meta Instant Games Unity Plugin

A Unity plugin that wraps the Facebook Instant Games SDK, enabling Unity WebGL games to access platform features such as player identity, social contexts, payments, tournaments, ads, and overlay views (NEZP — Network Enabled Zero Permissions).

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
• JSON builder — Chainable API for constructing JSON payloads without external dependencies

Requirements

• Unity 2022 or later
• Unity WebGL build target

Getting Started

Project Setup

1. Import the plugin 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.

Basic Usage

using Meta.InstantGames;

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

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

// 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.

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 and overlay view examples

Assemblies

Assembly	Scope	Description
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

Core API

The plugin is organized around a singleton FBInstant entry point with sub-APIs accessed via static properties:

Property	Description
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.

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 — Pass JSON data to templates and update dynamically
• Custom events — Handle user interactions from the overlay in C#
• CSS styling — Full CSS control over positioning and appearance
• Profile integration — Built-in helpers for player profile pictures and names

// Create an overlay from an XML file
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 with a tag palette, hierarchical tree, property inspector, and live XML preview.

Editor Tools

Tool	Menu Path	Description
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

Documentation

Full API reference documentation is available in documentation/API_REFERENCE.md, covering all classes, methods, data models, enums, and infrastructure components.

Contributing

See CONTRIBUTING.md for details on how to contribute, including the pull request process and Contributor License Agreement.

License

Copyright (c) Facebook, Inc. and its affiliates. All rights reserved.

The examples provided by Facebook are for non-commercial testing and evaluation purposes only. Facebook reserves all rights not expressly granted.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL FACEBOOK BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

This site is open source. Improve this page.