Contents

Bits in Extensions Guide

Introduction

Bits in Extensions enables developers to activate specific actions and “micro-experiences” in the extensions they build, in exchange for a viewer’s Bits used within the extension. Once broadcasters activate a Bits-enabled extension on their stream, their viewers can perform an action within the extension. If there are not enough Bits in the viewer’s account to perform the desired action, the extension can facilitate buying more Bits, to complete the action. (The extension takes the viewer to a separate system that handles Bits purchases, outside extensions.)

Revenue from Bits used directly in an extension is shared between the broadcaster and the extension developer.

To use Bits in Extensions:

  1. If you are not a Twitch partner/affiliate, complete monetization onboarding.
  2. Configure your extension for Bits:
    • Log into the developer site, https://dev.twitch.tv.
    • In the top row, click Your Dashboard.
    • Click the Extensions tab, to go to your Extensions dashboard.
    • In the Status column, click the version you want to monetize. The Version tab opens.
    • Click Extension Capabilities.
    • Under Will you monetize your Extension?, select Yes, I intend to monetize this Extension using Bits. (If you do not select this, your getProducts call will not return any products.)

      Note: You can change your selection until the first version of your extension is released. Once your extension is released, these options are disabled and you need to create a new extension to enable Bits.
  3. Manage your extension’s Bits product catalog. After you enable Bits monetization for your extension, you can manage your product catalog inside the developer rig. For more information on downloading and running the developer rig, see Extensions Developer Rig.

For More Information

For ...See ...
Current information on Bits pricinghttps://www.twitch.tv/bits
Bits-related reference informationExtensions Reference
Information to familiarize yourself with Extensions, before using Bits in ExtensionsAll the Extensions documentation
Information on JSON Web Tokens (JWTs), including how to verify themhttps://jwt.io/

Monetization Onboarding

When you are ready to add monetization (with Bits) to your extension on Twitch, non-Twitch partners/affiliates need to complete the Extensions monetization onboarding process. This allows you to create products to use in your extension.

During monetization onboarding, we require your tax and financial information, so we can validate your identity and pay out any revenue you earn.

Fill out the onboarding form carefully. To change information later, you must redo the entire form.

Note: If you are already a Twitch partner or affiliate, you do not need to onboard.

Procedure for Non-Twitch Partners/Affiliates

  1. Go here.
  2. Click Continue to Onboarding.
  3. Follow the steps on the page, to go to the onboarding form.
  4. Complete all sections of the form:
    • Register as a developer. Complete the fields with information about the legal entity that owns the extension. This information must exactly match your tax information and financial information, so make sure it is correct.

      Each legal entity can have only one Extensions developer account. If you have multiple individuals under one legal entity, please do not complete the onboarding multiple times; instead, have all your users utilize your one onboarded Twitch account.
    • Agree to the Twitch Extensions Developer Agreement.

      If you are under 18, this section asks your parent or legal guardian to agree to the agreement on your behalf. Your parent or legal guardian must enter his/her full legal name, check the box, and click Agree.

      For help interpreting the contract, please contact your attorney. (Twitch is not equipped to help with this.)
    • Complete two tax interviews, for royalty tax and service tax. The two forms are very similar but used for different purposes. Both need to be filled out accurately.

      Since Twitch is a subsidiary of Amazon, we use some Amazon tools to help Extensions developers get registered, including the tax-information forms. For definitions of individual fields, see the Amazon Tax Information Interview Guide.

      For help with this section, please contact your tax professional. (Twitch is not equipped to help with this.)
    • Provide financial information, to finish the process of validating your identity. Also, providing this information enables you to participate in monetization features that may become available. In this section of the form, you select how you want to be paid.

      On the Payment Method screen, we recommend you select Hold My Payments. You can modify this selection later if desired.

      In this step, we request some personal financial information so we can validate your identity, as mentioned above.

      This section may ask you for additional information. If you get this prompt, please submit a scanned copy of your government ID, such as a passport.
  5. When you finish providing all requested financial information, the approval process will begin. It can take up to 48 hours. If you are approved, you will get a notification email. If you are not approved, information is provided in Extensions Monetization Developer Onboarding; return there if you do not get the approval email within 48 hours.

Changing Information After Onboarding

To change your payment method, select Change Payment Method.

To change other information, on the Extensions Monetization Developer Onboarding main menu, click Start Over. This clears any information you have in our system, so you must complete the entire onboarding process again.

Bits Product Catalog

If your extension is enabled for Bits monetization, when you configure the developer rig to run with your extension, you will see a Manage Products tab. Here, you can view, create, edit, and deprecate products — as long as your extension is enabled for Bits and you are logged in to the account that owns your extension.

To create a product:

  1. Click Add Product. This adds an unsaved new product to the list of your products.
    If you click Add Product too many times, refresh the page to get rid of all unsaved changes.
  2. Set the fields as desired (see descriptions below). All fields are required.
  3. Click Save All, to save the new product to your catalog.
    Once you save a product, you cannot delete it (you can only deprecate it) or change its SKU.

A catalog can contain at most 250 products.

To edit a product:

  1. Change fields as desired (see descriptions below). All fields are required.
    While you are editing, the purple dot on the right indicates a product was edited.
  2. Click Save All, to save all edited and new products.

You cannot delete a product, but you can deprecate it, so it no longer shows up to end users, to be exchanged for Bits. Deprecated products are not included in the products returned by getProducts. To deprecate a product:

  1. Click Deprecate next to the product.
  2. Click Save All.

To restore a deprecated product:

  1. Click Restore next to the product.
  2. Click Save All.

Here are the catalog fields:

Field NameDescription and Restrictions
Product NameName of your product, to be displayed in your extension. Maximum length: 255 characters.
SKUSKU of your product. This must be unique across all your products. It cannot contain white space. Maximum length: 255 characters. The SKU cannot be changed after saving.
Amount (in Bits)Number of Bits for which your product will be exchanged. Valid value: 1 - 10000.
In DevelopmentToggles whether your product is “in development,” hence not included in the products returned by getProducts in production. Default: Yes.
BroadcastToggles whether your product triggers a broadcast when it is exchanged for Bits. Products that trigger a broadcast will submit a message to PubSub, to alert all instances of your extension (viewers on a channel) that a Bits exchange for the product was completed. Default: Yes.

Overview of Operations

Initialization

Initialization flow of a bits-enabled extension

Normally, an extension does bootstrapping or initialization operations in the onAuthorized callback. For Bits in Extensions purchases, getProducts also must be called, to get Bits products.

Getting Bits-in-Extensions Products

The amount of Bits necessary to exchange for a product is a flat rate, regardless of the viewer’s region. To display the amount to the viewer, the extension helper for Bits in Extensions uses the getProducts function. You call getProducts as part of your extension’s initialization process, to get the correct list of products that you will display on your extension’s storefront. This helper method returns a promise, which you can use as follows:

Twitch.ext.bits.getProducts().then(function(products) {
  console.log(products); // [ { sku: 'abc123', cost: { type: 'bits', amount: '10' } } ]
});

Exchanging Bits for a Product

When a viewer wants to use Bits within an extension, you call the useBits function on the extension helper. This function takes in the SKU of the product the viewer wants to exchange. The function is invoked as follows:

let productSku = 'abc123';
Twitch.ext.bits.useBits(productSku);

When useBits is invoked, if the viewer is logged in, the Twitch UI displays a dialog, showing:

Note that before confirmation, while the dialog UI is open, users are blocked from interacting with the extension. Clicking anywhere outside the dialog causes it to close and allows the user to interact with the extension again. Also, the user can cancel the flow at any point in the process.

When the user confirms the transaction, the Bits amount displayed in the dialog is locked in.

When processing is completed, a message is sent to your extension front end through the onTransactionComplete callback:

If ...Then ...
The product is configured in the catalog to broadcast to all users.A message is sent to all instances of your extension running on the channel where the Bits transaction was initiated.
The product is not configured to broadcast to all users.

A message is sent only to instances of your extension running on the channel where:

  • the Bits transaction was initiated and
  • the viewer who initiated the transaction is logged in.

If the viewer is not logged in when useBits is invoked, the UI indicates that login is required, to use Bits within an extension. If there is any other error (e.g., the user is banned or the SKU was removed from the catalog after products were loaded by the extension front end), a generic error message is displayed to the user. This message disappears after 3 seconds.