In-app Promotions

Promo codes let you give content or features away to a limited number of users free of charge. After you create a promo code, you can distribute it subject to the terms of service. The user enters the promo code in your app or in the Google Play Store app and receives the item at no cost. You can use promo codes in many ways to creatively engage with users, such as the following:

• A game could have a special item, such as a character or decoration, that's only available to players who attend an event. The developer could distribute cards with promo codes at the event, and users would enter their promo codes to unlock the item.
• An app developer might distribute promo codes at local businesses to encourage potential users to try the app.
• An app developer might give friends and family codes to its employees to share with their friends.

Every promo code is associated with a particular product ID (also known as a SKU). You can create promo codes for your existing in-app products. You can also keep an SKU off the Play Store, so that the only way to get that item is by entering that SKU's promo code. When a user enters the promo code in the Play Store or in an app, the user gets the item, just as if they paid full price for it. If your app already uses In-app Billing Version 3 to support in-app purchases, it's easy to add support for promo codes.

Creating and Redeeming Promo Codes

You create promo codes through the Google Play Developer Console. Each promo code is associated with a single product registered in the developer console.

A user can redeem a promo code in one of these two ways:

• The user can enter the promo code as part of the app's ordinary purchase flow, as described in Implementing In-app Billing. As far as the app is concerned, this is just like an ordinary purchase, except that the user makes payment with a promo code instead of with money.
• The user can redeem the code in the Google Play Store app. Once the user enters the code, the Play Store prompts the user to open the app (if they have the latest version installed) or to download or update it. Google doesn't currently support redeeming promo codes from the Google Play web store.

Supporting Promo Codes in Your App

To support promotion codes, your app must call the getPurchases() method whenever the app starts or resumes. This method returns a bundle of all current, unconsumed purchases, including purchases the user made by redeeming a promo code. The simplest approach is to call getPurchases() in your activity's onResume() method, since that callback fires when the activity is created, as well as when the activity is unpaused. Calling getPurchases() on startup and resume guarantees that your app finds out about all purchases and redemptions the user may have made while the app wasn't running. Furthermore, if a user makes a purchase while the app is running and your app misses it for any reason, your app still finds out about the purchase the next time the activity resumes and calls getPurchases().

Your app should allow users to redeem promo codes inside the app itself. If your app supports the in-app purchase workflow (described in Making In-app Billing requests), your app automatically supports in-app redemption of promo codes. When you launch the in-app purchase UI, the user has the option to pay for the purchase with a promo code. Your activity's onActivityResult() method receives a response intent telling the app whether the purchase was completed. However, your app should still call getPurchases() on startup and resume, in case the purchase and consumption workflow didn't complete. For example, if the user successfully redeems a promo code and then your app crashes before the item is consumed, your app still receives information about the purchase when the app calls getPurchases() on its next startup.

Your app should also support the scenario where a user redeems a promo code in the Play Store app while the app is running. Your app can find out right away when the user redeems a code by registering a listener for the PURCHASES_UPDATED intent. The Play Store fires this intent whenever a user redeems a promo code.

To listen for the PURCHASES_UPDATED intent, dynamically create a BroadcastReceiver object and register it to listen for com.android.vending.billing.PURCHASES_UPDATED. Register the receiver by inserting code similar to the following in your activity's onResume() method:

IntentFilter promoFilter =
    new IntentFilter("com.android.vending.billing.PURCHASES_UPDATED");
registerReceiver(myPromoReceiver, promoFilter);

When the user makes a purchase, the system invokes your broadcast receiver's onReceive() method. That method must call getPurchases() to see what purchases the user has made.

To reduce system overhead when your app isn't running, your activity's onPause() method must unregister the broadcast receiver:

unRegisterReceiver(myPromoReceiver);

Note: Don't register this broadcast receiver in the app manifest. Declaring the receiver in the manifest can cause the system to launch the app to handle the intent if the user makes a purchase while the app isn't running. This behavior is not necessary and may be annoying to the user. To find out about any purchases the user made while the app wasn't running, call getPurchases() when the user launches the app.

Testing In-app Promotions

If your app supports in-app promotions, test the following use cases.

User redeems promo code in the app

If the user redeems a promo code within the app's purchase flow, as described in Making In-app Billing requests, the system invokes your activity's onActivityResult() method to handle the purchase. Verify that onActivityResult() handles the purchase properly, whether the user pays with money or a promo code.

User redeems promo code in the Google Play Store

If the user redeems a promo code in the Play Store, there are several possible workflows. Verify each one of these workflows.

App is not installed

If the user redeems a promo code for an app that is not installed on the device, the Play Store prompts the user to install the app. (If the app is installed but not up-to-date, the Play Store prompts the user to update the app.) Test the following sequence on a device that doesn't have your app installed.

1. The user redeems a promo code for the app in the Play Store. The Play Store prompts the user to install your app.
2. The user installs and launches your app. Verify that on startup, the app calls getPurchases() and correctly detects the purchase the user made with the promo code.

App is installed, but not running

If the user redeems a promo code for an app that is installed on the device, the Play Store prompts the user to switch to the app. Test the following sequence on a device that has your app installed but not running:

1. The user redeems a promo code for the app in the Play Store. The Play Store prompts the user to switch to your app.
2. The user launches your app. Verify that on startup the app calls getPurchases() and correctly detects the purchase the user made with the promo code.

App is installed and running

If the user redeems a promo code for an app that is currently running on the device, the Play Store notifies the app via a PURCHASES_UPDATED intent. Test the following sequence:

1. The user launches the app. Verify that the app has properly registered itself to receive the PURCHASES_UPDATED intent.
2. The user launches the Play Store app and redeems a promo code for the app. The Play Store fires a PURCHASES_UPDATED intent. Verify that your app's BroadcastReceiver.onReceive() callback fires to handle the intent.
3. Your onReceive() method should respond to the intent by calling getPurchases(). Verify that your app calls this method and that it correctly detects the purchase the user made with the promo code.
4. The user switches back to your app. Verify that the user has the purchased item.