Migrating from Canvas Games

Note: For cases where your Canvas Game App ID differs from your Instant Game App ID, an Application Migration is required. You can access this through Gaming Services > Migration in the App Dashboard. This links the two App IDs so that player identity can be mapped between them.

• December 1, 2026: In-app purchases (IAP) on the Web Games version will be turned off. We recommend providing notice to your end users to set their expectations accordingly.
• December 30, 2026: Web Games that have not completed migration will no longer be accessible by end users on Facebook.

1. Add the Instant Games product to your existing Web Game application in the App Dashboard.
2. Upload an Instant Games bundle built with SDK 8.0 to your Web Game application by August 31, 2026.

1. Upload an Instant Games bundle built with SDK 8.0 to your Instant Games application by August 31, 2026.
2. In the Cross play management setting of your Instant Games, link the original Web Game application as the Linked Off-Platform App for your migration.

• September 1, 2026: In-app purchases (IAP) will be turned off for Web Games that are not migrating. We recommend providing notice to your end users to set their expectations accordingly.
• September 30, 2026: Web Games that are not migrating will no longer be accessible by end users on Facebook.

1. Go to the App Dashboard.
2. Select your existing app.
3. In the left sidebar, click Add Product and select Instant Games.
4. Complete the initial Instant Games setup, including uploading a placeholder bundle.

Note: If you are unable to find or add the Instant Games product to your app, please contact your partner manager or contact support.

Select Zero Permissions in the Connection Experience Settings page. This will begin the transition of your game from standard permissions to Zero Permissions.

Submit a request for Zero Permissions Advanced Access through the App Review > Permissions and Features interface. This is required for games undergoing Canvas-to-Instant Games migration, as it allows your application to exist in both Canvas and Instant Games states during the course of the migration. This Advanced Access will revert to Standard Access when the migration is complete. Direct link: https://developers.facebook.com/apps/YOUR_APP_ID/app-review/permissions/

Check the Instant Games > Launch Status page for any health check items that need to be resolved before your game can go live. Direct link: https://developers.facebook.com/apps/YOUR_APP_ID/instant-games/launch-status/

• If prompted, go to Instant Games > Audience Details to confirm your app details and submit an IARC certificate. Direct link: https://developers.facebook.com/apps/YOUR_APP_ID/instant-games/audience-details/
• If prompted, go to the Instant Games > Migration page and confirm the User data deletion clause. You must agree to delete all personally identifiable information (name, profile picture, friends data) within 90 days of starting migration. Direct link: https://developers.facebook.com/apps/YOUR_APP_ID/instant-games/migration/
• Once added, configure and confirm your game details under Instant Games > Details. Direct link: https://developers.facebook.com/apps/YOUR_APP_ID/instant-games/details/

Note: If you prefer, you can also create a new app specifically for the Instant Games version. This can be useful if you want to run both versions side by side during the transition, but be aware that players will have separate identities and data between the two apps. More information on identifying players between Canvas and Instant Games can be found here.

window.fbAsyncInit = function() {
  FB.init({
    appId: 'YOUR_APP_ID',
    cookie: true,
    xfbml: true,
    version: 'v18.0'
  });
};

FBInstant.initializeAsync().then(function() {
  // SDK is ready. Load your game assets here.
  // Report loading progress to the platform:
  FBInstant.setLoadingProgress(50);

  // When your game is fully loaded and ready to play:
  FBInstant.startGameAsync().then(function() {
    // The loading screen is dismissed. Start gameplay.
    startMyGame();
  });
});

FB.getLoginStatus(function(response) {
  if (response.status === 'connected') {
    var userId = response.authResponse.userID;
    var accessToken = response.authResponse.accessToken;
    // Use accessToken to call Graph API
  }
});

// After initializeAsync() resolves:
var playerID = FBInstant.player.getID();       // Unique to your game

// For server-side verification:
FBInstant.player.getSignedPlayerInfoAsync('my_request_payload')
  .then(function(result) {
    var signature = result.getSignature();
    // Send signature to your server for verification
  });

Note: To display the player’s name or photo, use overlay views. See Displaying the Current Player’s Profile for examples.

• There is no login prompt. The player is always authenticated.
• The player ID from FBInstant.player.getID() is not the same as the Facebook user ID you received in Canvas Games. It is a game-scoped ID. See Player Identification Post Migration for how to map players between your Canvas Game and your Instant Game using the available APIs.
• There is no access token and no direct Graph API access from the client. All social data is accessed through the Instant Games SDK.
• Player names and photos are rendered through overlay views and cannot be accessed directly in your game code.

Friends

FB.api('/me/friends', function(response) {
  // response.data contains friends who also use the app
});

FBInstant.player.getConnectedPlayersAsync()
  .then(function(players) {
    players.forEach(function(player) {
      console.log(player.getID());
    });
  });

Sharing

FB.ui({
  method: 'feed',
  link: 'https://apps.facebook.com/mygame/',
  caption: 'I just scored 1000 points!'
});

FBInstant.shareAsync({
  intent: 'SHARE',
  image: base64EncodedImage,  // Base64-encoded image data
  text: 'I just scored 1000 points!'
}).then(function() {
  // Share was completed
}).catch(function(error) {
  // Share was cancelled or failed
});

Invitations / Requests

FB.ui({
  method: 'apprequests',
  message: 'Come play my game!'
});

// Choose a context (conversation) to play in:
FBInstant.context.chooseAsync().then(function() {
  // Player selected a friend or group. Send an update:
  FBInstant.updateAsync({
    action: 'CUSTOM',
    cta: 'Play Now',
    image: base64EncodedImage,
    text: {
      default: 'Come play with me!',
    },
    template: 'invite',
    strategy: 'IMMEDIATE',
    notification: 'PUSH',
  });
});

In-App Purchases

FB.ui({
  method: 'pay',
  action: 'purchaseitem',
  product: 'https://myserver.com/products/gems_100.html',
  quantity: 1
}, function(response) {
  // Handle purchase callback
});

// Get the product catalog
FBInstant.payments.getCatalogAsync().then(function(catalog) {
  catalog.forEach(function(product) {
    console.log(product.productID, product.title, product.price);
  });
});

// Make a purchase
FBInstant.payments.purchaseAsync({
  productID: 'gems_100',
  developerPayload: 'optional_payload'
}).then(function(purchase) {
  // Purchase successful
  console.log(purchase.purchaseToken);

  // Consume the purchase (for consumable products)
  return FBInstant.payments.consumePurchaseAsync(purchase.purchaseToken);
}).then(function() {
  // Purchase consumed, grant the item to the player
});

In-App Advertising

Note: Interstitial ads have been replaced by Rewarded Video ads.

// Rewarded video
FBInstant.getRewardedVideoAsync('YOUR_PLACEMENT_ID')
  .then(function(rewarded) {
    return rewarded.loadAsync();
  })
  .then(function(rewarded) {
    return rewarded.showAsync();
  })
  .then(function() {
    // Player watched the ad. Grant the reward.
  });

// Interstitial ad
FBInstant.getInterstitialAdAsync('YOUR_PLACEMENT_ID')
  .then(function(interstitial) {
    return interstitial.loadAsync();
  })
  .then(function(interstitial) {
    return interstitial.showAsync();
  });

// Save data
FBInstant.player.setDataAsync({
  level: 5,
  score: 1200,
  inventory: ['sword', 'shield']
}).then(function() {
  // Data saved
});

// Load data
FBInstant.player.getDataAsync(['level', 'score', 'inventory'])
  .then(function(data) {
    console.log(data.level);  // 5
    console.log(data.score);  // 1200
    console.log(data.inventory);  // ['sword', 'shield']
  });

Data migration with ASIDs

1. Set up the Cross-play management tool through Instant Games > Audience Details in the App Dashboard to link your legacy app and the Instant Game.
2. In your Instant Game, call FBInstant.player.getASIDAsync() to retrieve the ASID, which matches the legacy Canvas user ID.
3. Use the ASID to look up the player’s existing backend data and merge it with their new Instant Games Player ID.

• Providing a one-time migration code that players can enter in the Instant Game to recover their progress.
• Accepting that some players may start fresh, and focusing your migration effort on active, high-value players.

1. Place all of your game files in a single directory with index.html at the root.
2. Include your fbapp-config.json configuration file at the root. See Bundle Configuration.
   Minimally, your file structure should look like this:

   bundle/
   |  index.html
   |  fbapp-config.json
   
3. Create a ZIP file of the directory contents (not the directory itself — index.html should be at the top level of the ZIP).
4. Go to the App Dashboard, select your app, and navigate to Instant Games > Web Hosting.
5. Upload the ZIP file as a new build.
6. Mark the build as the active build for testing, or push it to production when ready.

• Loading flow: Ensure initializeAsync() and startGameAsync() work correctly and the loading progress bar behaves as expected.
• Player identity: Verify that player IDs are being handled correctly and that your game does not accidentally use stale Canvas-era user IDs. See Player Identification Post Migration for details on mapping player identities across platforms.
• Social features: Test sharing, connected players, and context switching.
• Monetization: Test purchases using test users and verify that ad placements load and display correctly.
• Data persistence: Verify that saving and loading player data works reliably.
• Cross-platform: Test on iOS, Android, and web. Canvas Games only ran on the web, but Instant Games run on mobile as well. Ensure your game’s UI and controls work on touchscreens.

• ASID Override is a feature that allows you to override the ASID of a test user. This is useful for testing the migration flow.
• Setting the test migration toggle will serve the Instant Game bundle to the testers.

When you are ready, submit your application for app review in Instant Games > Review > App Review for Instant Games. Once approved, you will be able to begin the rollout to your players. This process will take a few days, but you can continue to test your game in the meantime.

Note: Rolling out is only incremental and cannot be rolled back.

• Add Instant Games directly to your existing Web Game app in the developer portal.
• No new app ID needed. Your Web Game app becomes both your Web Game and Instant Game app.
• Best for teams that want to preserve their existing app ID and avoid player ID remapping.

• Create a new app that will serve as your production Instant Games app, then link it to your Web Game app through the cross-play flow.
• Best for teams that prefer a clean separation between their Web Game and Instant Game builds.

• Review documentation. Read this guide, the Zero Permissions Overview, and the SDK Reference.
• Audit current architecture. Identify all server-side rendering, Graph API calls, and Facebook Payments integrations that need to be replaced.
• Plan data migration. Formulate a strategy for mapping legacy Canvas user IDs (ASIDs) to new Instant Games Player IDs to preserve player progress.
• Prepare assets. Ensure you have the required assets: 800x800 game icon, 1200x630 landscape cover, 1080x1080 square cover, and a gameplay MP4 video.
• Set up the App Dashboard. Decide whether to add the Instant Games product to the existing app or create a new one.

• Restructure the client. Convert the game to a static client-side bundle with an index.html entry point.
• Configure the bundle. Create the fbapp-config.json file at the root.
• Implement SDK initialization. Integrate initializeAsync(), setLoadingProgress(), and startGameAsync().
• Update identity. Replace legacy authentication with FBInstant.player.getID() and implement the ASID linking logic with FBInstant.player.getASIDAsync().
• Migrate social APIs. Replace Graph API sharing and friend requests with Instant Games social APIs (shareAsync, updateAsync, getConnectedPlayersAsync).
• Migrate monetization. Recreate IAP products in the App Dashboard and implement the new client-side purchase flow. Integrate Audience Network ads if applicable.
• Enable Zero Permissions. Toggle Zero Permissions in the App Dashboard if your game requires external server communication via HTTPS.
• Request Advanced Access. Submit a request for Zero Permissions Advanced Access through App Review > Permissions and Features to allow your app to exist in both Canvas and Instant Games states during the migration.

• Local testing. Test game logic locally using a mock SDK or local HTTPS server.
• Platform testing. Upload the bundle to Web Hosting and test on the platform.
• Cross-device testing. Verify functionality on iOS (Facebook app), Android (Facebook app), and desktop web (facebook.com/gaming). Ensure the UI is responsive to different screen sizes.
• Social and IAP testing. Use App Dashboard test users to verify connected players, sharing, and in-app purchases.
• Performance testing. Ensure the game loads in under 5 seconds on average networks and handles network interruptions gracefully.
• App review and quality review. Submit the game for Instant Games Quality Review and ensure all required permissions and IAP reviews are approved.
• Legal and configuration check. Verify that the Privacy Policy URL, Terms of Service URL, Data Deletion Callback, and Business Verification are complete.
• Push to production. Select the approved version in Web Hosting, click Push to Production, and switch the App Mode to Live.
• Post-launch monitoring. Monitor analytics (DAU, retention, session length) and watch for crashes, errors, or long load times in the early days after launch.

• SDK Reference — Complete API documentation for the Instant Games SDK.
• Player Identification Post Migration — How to map player identifiers between Canvas Games and Instant Games.
• Game Testing — Comprehensive testing guide.
• FAQ — Answers to frequently asked questions.
• Get Support — Support channels for developers.

1. Optimize performance. Review Game Performance to ensure fast loading and smooth gameplay.
2. Enhance social features. Explore Retain for guides on tournaments, challenges, and other social features that were not available on Canvas.
3. Launch. Follow the Launch checklist to submit your game for review and go live.