Instant Games FAQ

General Info about Instant Game

You can find them by clicking on the GAMES bookmark on left hand column on Facebook.com - you will be redirect to https://www.facebook.com/games/instantgames. If you are a recurring players, you should see also an Instant Games unit in the right hand column with a MORE link.


Developing an Instant Game

If you can't see "Instant Games" in the list when selecting "Add Product" to your application, make sure that your app is in the "Games" category. The "Instant Games" product will not show up for apps outside of this category.

We don't impose hard limits on game size. But we do recommend that the initial download size not exceed 5 seconds. You can host up game bundles of up until 200MB but you should only download absolutely necessary files in the initial load. For more information please refer to our Best Practices section

When it comes to deciding where to store your information, there are two options:

  1. Having a third-party backend that your game communicates with via XMLHttpRequest, fetch, WebSocket or EventSource. This will mean more flexibility but will also incur hosting costs that are proportional to your game's audience.
  2. Using our SDK-based solutions that enable many server-side functionality out of the box: a. For storing player-specific information, use our player.getDataASync and player.setDataAsync methods b. 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. See more tools here.

The minimum system requirements for playing instant games are:

  • iOS 8 and above
  • Android 5.0 and above

Consult our lightweight games documentation to get more details about the minimum requirements for lightweight games.

You can report issues directly on Howler.js Github. 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 even edit) tracks from Facebook's Sound Collection in your games. Do note that 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/used on our platform.


Adding features to an Instant Game

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

This is currently not possible. When you are 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 to use a placeholder name like "opponent" until the second player responds to the invite, when you'll be able to access their information via FBinstant.player.


Monetizing an Instant Game


Advertising

Go to https://www.facebook.com/business/resources to find out more.


Payments

On-Boarding 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 or PayPal (bank name, account number or IBAN, country, SWIFT code or routing number)
  • Paypal (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 Application and Page Admins have access to both app and page-level features, but cannot edit financial information.

Rules regarding how taxes apply to your account can be found in section 3.9 within our payment terms here.

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.

Please keep in mind that Facebook only sends payments in United States dollars. If your bank requires an intermediary or correspondent account in order to receive USD payments, please also 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 around the 2nd week of the month. The account number on this invoice is an internal number for our record keeping, this is not your bank account number.

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 3rd 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.

Whenever 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. All payments terms can be found in full here.

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

Please contact Facebook support for payment and reporting questions. For any 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.

Escalating the issue elsewhere and/or reopening an additional ticket, will delay and additionally complicate your existing inquiry with our Payments Operations team. We strongly advise all partners to channel all updates/follow ups through the existing communication channel you have open 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 taken care of.


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 is able to receive payments in USD.
  3. Review your payout account information to confirm it's still 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 the our payments help page here. Whenever 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 or bank letter on the appropriate letterhead or a screenshot from PayPal.

If you are the admin of the account, you will be able see the Financial Entity associated with your account within your business manager dashboard here. If you would like to be added as a financial account administrator, please 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 Facebook Payment Support for Monetizers form here. And select Game / App (Developer) > Update account records > Change the organization associated with my app or Facebook page.

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

If you have developed apps that use Facebook payments and subscription features, you can get a full breakdown of your refunds and chargebacks activity, by using the reports feature of Facebook payments. A full guide detailing the contents of these reports and how to pull them can be found here.


Publishing an Instant Game

To restrict the access to your game 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 on "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 4.7. 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. We created this limit to help you, as a developer, be successful as you launch your game.

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.

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

You can report a privacy rights violation here. Please note that this channel is reserved for people reporting potential violations of their privacy rights concerning their image on Facebook.


Game bots

The most common cause for a bot not receiving webhooks is misconfiguration in the app. Please visit our Bot Setup section for a full guide on how to setup your game bot. Check your developer dashboard for the following:

  1. You need to have an App Page configured in the Instant Games section of the developer dashboard
  2. You need to have subscribed to the messages and messaging_game_plays events in the Messenger section of the developer dashboard
  3. You need to have the same page as step (1) above configured in the "subscribed pages" panel, in the Messenger section of the developer dashboard
  4. Your page needs to be of category "App Page" and needs to have a name that contains your game name.

If you're getting errors as response to the Graph API send calls, it means that 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; or
  • You're trying to send messages to a user who has deleted, blocked or muted your bot; or
  • 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 please refer to the Send API documentation


Common issues and troubleshooting

If you're following either of 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 the loading. Sometimes no message will be displayed in the browser's developer console, and some other times a message will be displayed saying Failed to execute 'postMessage' on 'DOMWindow'. These are both manifestations of the same type of error, most commonly caused by your local server is 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 be working.

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 rejected once already, don't try to reuse it. Instead, request a new AdInstance by calling getInterstitialAsync or getRewardedVideoAsync