Instant Games FAQ

General Info

Log in to Facebook.com and click the Games bookmark on the left, or visit https://www.facebook.com/games/instantgames.


Developing a Game

Make sure your app is in the Games category. The Instant Games product will not show up for apps outside this category.

While we don't impose hard limits on game size, we do recommend that the initial download time not exceed 5 seconds. You can host game bundles of up to 200MB, but only require necessary files in the initial load. For more details, refer to our Best Practices section

When it comes to deciding where to store your information, you have several options:

  1. Have a third-party backend your game communicates with via XMLHttpRequest, fetch, WebSocket or EventSource. This will mean more flexibility, but will also incur hosting costs proportional to your game's audience.

  2. Use our SDK-based solutions, which enable server-side functionality out of the box. For storing player-specific information, use our player.getDataASync and player.setDataAsync methods. For leaderboards, see our Leaderboard API guide.

  3. Third party services like PlayFab provide fully cross-platform backend-as-a-surface platforms built to support LiveOps, matchmaking and analytics. Browse more tools.

The minimum system requirements for playing instant games are iOS 8 or Android 5.0.

Review our lightweight games guide for more information.

You can report issues directly on the Howler.js Github page. Put "[IG]" in the title of the issue to help the developers prioritize.

You should make sure to call window.innerWidth and window.innerHeight after FBInstant.startGameAsync() resolves.

You can use (and edit) tracks from Facebook's Sound Collection in your games. Sound Collection content can only be used on the Facebook platform, so any version of your game that incorporates Sound Collection content can only be distributed on our platform.


Adding features to a Game

Our FBInstant.context.shareAsync() method contains an intent parameter that accepts values like 'INVITE', 'SHARE', etc. As of version 4.0, this parameter does not serve a specific purpose. It was added to future-proof the SDK and it will provide user-facing changes in the future.

When you're challenging another player in the thread for the first time, there's no SDK method to retrieve information about the person being challenged. We recommend using a placeholder name like "opponent" until the second player responds to the invite. Once the other player has accepted the invitation to play, you can use FBinstant.player to fill in their picture and name.


Game Bots

The most common cause for a bot not receiving webhooks is misconfiguration in the app. Visit our Bot Setup page for a full guide on how to set up your game bot.

Check your Developer Dashboard to ensure that:

  1. You have an App Page configured in the instant games section
  2. You have subscribed to the messages and messaging_game_plays events in the Messenger section
  3. The App Page is configured in the Subscribed Pages panel in the Messenger section
  4. Your page is categorized as an App Page and has a name that contains your game name.

If you're getting errors in response to the Graph API send calls, it means one of the following situations is happening:

-You're trying to send messages outside of the per-user limit of 5 messages over 10 days

-You're trying to send messages to a user who has deleted, blocked or muted your bot

-Your app is in Development Mode and you're trying to send messages to people who don't have an Admin or Developer role in the app

For more information, review the Send API documentation.


Troubleshooting

If you're following our Quickstart or our Test, Publish, Share guides, you must be familiar with our concept of the Embedded player. It's a way for you to test your Instant Game running from a local HTTP service in your computer, linked to all live functions of the Instant Games SDK.

Sometimes when you try this approach, your game can be stuck in loading. Sometimes no message will be displayed in the browser's developer console, or a message will be displayed saying Failed to execute 'postMessage' on 'DOMWindow'. These stem from the same type of error, most commonly caused by your local server refusing to serve assets because of a certificate issue.

If that's the case, navigate to the root of your local server (usually https://localhost:8000 or https://127.0.0.1:8000) and follow your browser's instructions in accepting certificates, or adding a security exception for this website. Once you've done that, go back to the Embedded player URL and everything should work as normal.

This error happens when you are trying to load an ad from an AdInstance which has failed in the past. If your AdInstance's loadAsync method has been rejected once already, don't try to reuse it. Instead, request a new AdInstance by calling getInterstitialAsync or getRewardedVideoAsync.


Using Analytics

The Facebook Analytics email report gives you a quick overview helping you see highlights of your app activity and better understand the people using your app. Email frequency may vary between weekly and monthly, as we're testing the benefits of each option.

To unsubscribe from email reports, click unsubscribe here at the bottom of the email, and change your preferences under Developer Updates.

Alternatively, you can access your email controls directly from your developer settings.

For more information on your Facebook Analytics reports, visit our help center.


Monetizing a Game


Advertising


Payments

Onboarding with Facebook

To update your payment information:

  1. Go to the Facebook Developers site.
  2. Click My Apps and select Audience Network or Developer tab.
  3. Click the Payout tab.
  4. Select an existing Payout method or create a new one.

We can issue payouts to your bank or PayPal account (does not apply to Audience Netowrk users).

You will need:

  • Payout Account Information (address, tax type, tax ID)
  • Owner Information (name, address, birthdate)
  • Bank information (bank name, account number or IBAN, country, SWIFT code or routing number)
  • PayPal information (PayPal email, country, merchant ID)

Government agencies use tax ID numbers to identify both individuals and businesses when assessing any taxes required by law. Where you live and how your run your business factors into which tax ID numbers you'll need.

  • If you represent a business in the United States or European Union, you'll need to provide a federal employer identification number (FEIN) or a value-added tax identification number (VAT.)
  • If you run your business individually as a sole proprietorship, you'll need to provide a social security number (SSN) or other tax identification (ex: country ID or passport number.)
  • If you live outside of the United States and European Union, you'll need to provide an applicable identification number issued by a government agency. This number should not only uniquely identify you or your business, but it should also be associated with your Audience Network Account.

Payout Account Admins have the ability to edit company and financial information, while App Admins and Page Admins have access to both app and page-level features, but cannot edit financial information.

Tax details can be found in section 3.9 of our Payments Terms page.

Using Payout Account Information

To update your payout account and financial information, you must be the Financial Admin of your payout account.To update your account information:

  • Go to the Facebook Developers site.
  • Click your profile photo in the top right corner and select Company Settings.
  • Choose the appropriate tab to update your company or financial info. Scroll to the bottom and click Save Changes.

Please note, it may take a few days to finalize any changes you make to your company or financial information. Additionally, your ability to receive your payout may be affected if you edit any info before a payment is scheduled.

You must be the Financial Admin of your payout account to modify or add new users. To update or add someone as an admin:

  1. Visit the Facebook Developers site.
  2. Click your profile photo in the top right corner and select Company Settings.
  3. Click Admins.
  4. Enter the name of the new admin and then click Save Changes.

Facebook only sends payments in United States dollars (USD). If your bank requires an intermediary or correspondent account in order to receive USD payments, please include the following:

  • Intermediary Bank Name
  • Intermediary Bank Country
  • Intermediary SWIFT code

Status of Payout

Audience Network

You'll receive payments around the 21st of each month for the previous month's balance.

Developers and Charities

Facebook issues payments twice per month: One payment for activity between the 1st and the 15th of the month, and a second payment for activity between the 16th and the end of the month. Facebook will issue payments approximately 21 days after the end of each bimonthly period. Visit the Facebook Developer Payments Terms for more information.

To check the status of your payment:

  1. Visit the Facebook Developers Site.
  2. Click the Audience Network tab.
  3. Click the Payout tab.
  4. Select Payment Reports to view your app's payments status.

If the status shows "Rejected/Pending Payment", please confirm that your Payout Account Detail Information is accurate. Additionally, you can also contact us by clicking on the "Need Help?" button within the Audience Network Dashboard for further information.

An invoice shows your monthly earnings over the course of a month. Your account's invoice is generated by our finance team before payment. The account number on this invoice is an internal number for our records.

A remittance statement shows the amount paid by Facebook to your account for your earnings over the course of a month. When our bank initiates the payment to your bank account you will receive a remittance statement around the third week of the month.

In order to review your current balance, please view your daily reports and payout reports to calculate your current balance via our payments API. You can download daily reports for the previous 45 days.

When you complete a sale on our platform, Facebook will credit the proceeds from that sale, less our service fee, to your Developer Balance. Facebook will earn a 30% service fee, plus any applicable sales tax or VAT, in connection with each Facebook Payments transaction on our platform. Review our Payments Terms for more details.

Payments are transferred to your linked account when you accumulate a minimum of $100 in revenue. If your payment balance is less than $100 for any given payment period, payment will be rolled over to the next payout cycle. Rollover will continue until your payment balance reaches $100.

For issues regarding your recent payouts, please submit an inquiry via the Facebook Payment Support for Monetizers Form. and select Game / App (Developer) > Payouts > I have a question about my recent payout.

For payment and reporting questions, contact Facebook Payment Support.

Escalating the issue elsewhere or reopening an additional ticket will complicate your existing inquiry with our Payments Operations team. We strongly advise all partners to channel followups through the existing communication channel you have with the Payments Operations team.

Privacy and Security

To verify you're the Financial Admin of your payout account, please visit the Facebook Developers site.

Facebook values the trust you place in us and takes the necessary steps to prevent unauthorized access to your information. We store your financial information on secured servers and take extra steps to protect this info from hackers.

While we may share your contact or other profile information according to our data policy, no banking or PayPal information is shared except as necessary when making payments or complying with legal requirements.

Facebook may store your information to prevent you from having to re-enter it for future payouts. Additionally, should you request that Facebook makes changes to your payment information, we may retain certain evidence supporting these changes (example: bank information).

If you're experiencing issues or have any payments questions, let us know and we’ll work with you to make sure the problem is addressed.


Getting Help on Payments

If you haven't received your payment by the 21st of the month, please check the following before contacting support:

  1. Verify that you have accumulated at least $100 in revenue.
  2. Contact your bank to ensure they haven't rejected the payment and that your bank account can receive payments in USD.
  3. Review your payout account information to confirm it's accurate.

If you have any questions or issues with your payouts account, please let us know.

If you need help updating the information in your account, please visit our [Payments help page(https://www.facebook.com/help/459445787770984). When financial information is updated, we place a 10 day hold on your account before processing a payment. We may be able to remove this hold more quickly if you send us proof of ownership of the bank or PayPal account. For proof, you can send us a bank statement, a bank letter on the appropriate letterhead, or a screenshot from PayPal.

If you are the admin of the account, you can view the Financial Entity associated with your account in your Business Manager Dashboard. If you'd like to be added as a financial account administrator, ask a current administrator for your organization. Once you're Facebook friends, they can add you directly on the Facebook Developers Site.

Please use our Payment Support for Monetizers form and select Game / App (Developer) > Update account records > Change the organization associated with my app or Facebook page.

Visit our Facebook Payment Support for Monetizers form, then select Game / App (Developer) > Update account records > Change the organization associated with my app or Facebook page.

If you've developed apps that use Facebook payments and subscription features, you can get a full breakdown of your refund and chargeback activity by using the Reports feature of Facebook Payments. A full guide can be found on our Payments Reports page.

We don't have a notification system, but we do include refund information in the remittance pdf we send every month.

Reimbursements are paid monthly, but the payout release period is 60 days, i.e., January's payout activities will be paid out in March.

Every player can access it from Settings, and specifically in the Payments section. Suggest players to learn more in Facebook Payments.


Publishing a Game

To restrict game access to a custom list of countries:

  1. On the dashboard of the application, go to Settings / Advanced
  2. Enable Country Restricted
  3. Select countries from the Allowed Countries selector
  4. Click Save Changes

During submission for instant game app review, you must provide an Apple Developer team ID in accordance with Apple's App Store Review Guidelines. This enables distribution of your game on iOS. Using an invalid or expired Developer team ID may lead to your game being removed.

You can find your team ID by logging into your Apple Developer Account.

Developer game submissions and launches are limited to one per week. You can submit and publish two games over the course of two weeks. One game can be reviewed by Facebook per week, and one game can be published per week, once it has been reviewed and approved. We created this limit to help you be successful as you launch your game.

To learn more about the review process, see the Submitting for Review section in the Launch Checklist.


Review Process

The Review tab of the developer dashboard allows you to submit your game to our review team.

You have to submit your game for the following reviews:

  1. Instant Games
  2. In-App Purchases
  3. Pages_messaging (for bots)

You need a Monetization Manager to submit your game for:

  1. Audience Network Ads monetization.

Before submitting your game for IAP review, the app must be approved for Audience Network.

Learn more about sending your app for review.

It typically takes our Developer Operation team less than one week to process your submission.

The purpose of each review is to ensure quality and integrity standards are met for on-boarding to the Instant Games platform.

Specifically, we screen games for compliance with functionality and Platform policy guidelines.

Before submitting for review, make sure to check the Release guidelines.

If your current submission requires additional information, you will have 30-days from receipt of the request to resolve and resubmit for review. During those 30-days you may be asked to provide more information by the App Review team. Please note that the 30-day window will not reset with each resubmission during this period.

Our review team will use the instructions you provide to test your app's Facebook integrations.

If you feel our reviewer has incorrectly rejected your app, you should resubmit for review with updated review instructions that provide more info for the reviewer.

The review process is the best way to communicate with your reviewer by updating your notes to address the feedback you've received.

Your app will be reviewed on each of the platforms you list in the Settings section of your App Dashboard. If you don't want a certain platform to be reviewed, including if you don't yet have a working version of your app on a specific platform, please remove it from your Settings page.

You can find more info in our documentation on platforms.

To approve your app submission, our review team will need to log into your app and check all Facebook integrations.

If your reviewer has been unable to load or use your app, please make sure that:

  • The App URL is publicly accessible and not configured as a localhost
  • You've provided the username and password needed to access your development or staging site
  • Your site's security certificates are up to date and not causing errors for new users
  • You're able to login and use your app as a newly created test user
  • The items you submitted for review are built out and working in your app

If you're rejected again for the same reason, update your Review Instructions or Add Notes section to ask your reviewer for some clarity and additional info.

For App Review, game submissions must linked to a business (verified or unverified).

For Global & Country Launches, the app's linked business must be verified to launch the game into our discovery surfaces (game list, etc). The game will still be playable after review approval.

To verify your business, you need to create a Business Manager. Find more info about Business Verification here.

You can always find the status of business verification and contracts and steps to take in the business verification panel found in the app review tab of the app dashboard. We will send you notifications throughout the process to let you know what action is needed.

If you already have a Business Manager account, we recommend that you connect the app to the existing Business Manager.

If there are multiple Business Manager accounts that belong to the business, we recommend determining the rationale for multiple Business Manager accounts and aligning the app with the most appropriate Business Manager. If the business has a credit line set up through the Business Manager, we recommend that you connect the app with the one that has the credit line.