In-app *purchases 🔗

Let's say you have created a supercool wild mushroom identification app. It has a part that is accesible to anyone with the link to the app, where you describe how it works and provide basic tips for identifying the most poisonous mushrooms. You have also created a fancy Premium section where the user answers questions about the mushroom they want to identify (e.g., the shape, color, etc) and you provide them with possible matches and detailed information about each of them. In order to access the Premium content of your app, your users need to pay a subscription.

We will walk you through the steps to:

  • Check if a user has an active subscription to access some content of your program.
  • Let the user subscribe if they don’t have a subscription.
  • Allow users to manage their subscription.

If your program runs on a web browser, you will need to create a merchant account on Braintree. If it is an app, payments will be managed either by Apple or Google. In this case study, however, we will assume you are just charging users on the web, and so will use Braintree, which has a developer sandbox that is very useful to test and debug your program.

Part 1: Set up a subscription on Braintree 🔗

You can create a Braintree Sandbox account for testing purposes here . When you are ready to go live, follow this link to apply for a Braintree account.

After logging into either account, navigate to Subscriptions and then click on Plans . Once there, click on New Plan .

Follow the instructions on the screen to set it up:

  • You will use Plan ID to identify the plan in your GuidedTrack program.
  • Plan Name should be descriptive and easily readable, as it is the name displayed to your subscribers when they manage their subscription.

Now you are ready to integrate with GuidedTrack! Before you leave the Braintree site, make sure to find your Merchant ID, Public Key and Private Key .

Part 2: Set up and code subscriptions in your program 🔗

First, go to your program Settings and select the Purchases tab:

Part 2 Set up and code subscriptions in your program (1)

Here you can see your three options for integrating purchases (Braintree, iOS or Android). Follow the instructions on the screen to configure your provider. In the case of Braintree, all you need to do is enter the Merchant ID, Public Key and Private Key that you have located on the Braintree website.

If you are using a Braintree Sandbox account to test your program, remember to come back here to update your credentials once you are ready to go live!

Once your program is set up, you are ready to add the code! How you manage subscriptions inside your program is independent of the service you are using to process the payments. In other words, the code in your program is the same regardless of the provider you use (Braintree, Apple or Google).

Check the status of a subscription 🔗

Before serving the Premium content of your app, you will want to check if the user has an active subscription that allows them to access it. You can use this code to do that:

>>purchaseStatusError = 0
*purchase
	*status
	*success
		>>subscriptionPaid = it["paid"]
		>>subscriptionOngoing = it["ongoing"]
		>>subscriptionExpiration = it["expiration"]
	*error
		>>purchaseStatusError = 1
		>>purchaseStatusErrorText = it["message"]

If the user of your program does not have an active subscription and never had it before, there will be an error with the message “ no purchase found ”.

Otherwise, the association it will have three keys:

  • paid: will take “yes” and “no” for values.
  • ongoing: “yes” when the subscription is set to auto renew and “no” when it is not.
  • expiration: Date when the subscription expires. It is in text format, use the *program: date format parser – public to convert it into a date variable if needed.
Subscribe a user 🔗

Use this code so that a user can subscribe:

*purchase: trialPlan
	*frequency: recurring
	*success
		>>userSubscribed = 1
	*error
		>>userSubscribed = 0

The name of the purchase (in the example, trialPlan ) must match the Plan ID that you created on Braintree.

Keep in mind that only logged-in users can subscribe . If they are not logged in, there will be an error and the it object will be { “step” -> purchase, “details” -> { “code” -> unauthorized, “message” -> user not signed in } } . You can configure your program settings ( Settings>Login ) so that anonymous users are prompted to log in or register when using your program.

Tip : Follow this link to find credit card numbers you can use when testing against your Braintree Sandbox Merchant Account.

Allow users to manage their subscriptions 🔗

Use

*purchase
	*management

to open a new tab or window in your user’s browser so that they can manage their subscription.

Your user’s browser may keep the program from opening a new window, you can avoid it by putting the code inside a clickable component:

*component
	Click here to manage your subscription
	*click
		*purchase
			*management

Managing your subscribers and deleting user's data 🔗

If a user that has a subscription requests you to delete all their data, there are two places where to delete: GuidedTrack and Braintree.

  • Have them access https://www.guidedtrack.com/account , logging in with the user/password they use to access your program. From there they can delete their GuidedTrack data.
  • Have them provide you the email address they use to log into your program. You will use that email to find their Customer ID on the Braintree Control Panel and delete their data.

If you are processing the payments via Google or Apple, users can delete their data themselves in the appropriate app for Android or iOS.


Next: