Home
Blog
Authors
Dan Burcaw

Dan Burcaw is Co-Founder & CEO of Nami ML. He built a top mobile app development agency responsible for some of the most elite apps on the App Store and then found himself inside the mobile marketing industry after selling his last company to Oracle.

Latest articles by
Dan Burcaw
Written by
Dan Burcaw
6 Nov

Fitting Paywalls to User Context – A Guide to Driving Conversions

Discover how to personalize your app paywalls to user context, device, and journey stage. Unlock tactics of paywall A/B testing to craft frictionless experiences that drive conversions.

Paywalls offer a clear path to monetization for subscription businesses. However, neglecting user experience in the pursuit of conversions is short-sighted. Frustrated users won't convert, and worse, won't return. A well-designed paywall that showcases value and prioritizes user experience can drive sustainable growth.

Great design is a cornerstone of user experience, but it's only part of the picture. Effective UX is all about understanding how users' needs and expectations shift depending on the context.

Imagine a football fan on their morning commute – they're quickly checking scores on their phone. But later, relaxing at home, they're engrossed in the game on their smart TV. A one-size-fits-all paywall won't resonate with these different user journeys.

Similarly, a user’s journey within the app also influences their receptiveness to a paywall. A new user might be curious about the app's core features, while a returning user might be more interested in premium functionalities that fit into the workflow they have already established for themselves within the app.

This is where context-aware paywall optimization comes in. By understanding user intent, device usage, and the stage of their journey within the app, you can tailor paywall messaging and design to resonate with individual users.

How do you stand to gain from this?

Not only does a user-centric paywall lead to higher conversion rates but also makes a positive user experience possible. It keeps users engaged in the long run, so you can hope for them to bring in recurring business over an extended period.

In this article, we delve into the power of context-aware paywall optimization. We'll explore the limitations of generic paywalls, discuss the importance of understanding user context and journey, and dive into strategies for creating personalized experiences that drive conversions – all with the intention of serving users the right kind of paywall that doesn't block access, but rather takes them to the other side where the grass is greener, so to speak.

👉Read more: Five Paywall Design Best Practices

What does it take to create personalized, optimized paywalls?

Think of a supermarket where every product has a generic sign that screams "Buy this now!". That wouldn’t be very interesting or effective, would it?

Wouldn’t it make more sense to see targeted messages like "healthy yogurt for your morning routine" or "fresh vegetables for your family dinner"? Paywalls that cater to user context are like those targeted signs – more relevant and likely to resonate.

People have different needs and expectations. A busy professional on their mobile phone while traveling to their office seeks a quick and informative experience, while someone relaxing on the couch with a smart TV? Well, they don’t mind browsing a wider range of content with previews or trailers on offer. A one-size-fits-all paywall ignores these crucial differences, leading to user frustration and lost opportunities for conversions.

Understanding user context

The key to unlocking effective paywalls lies in understanding the context in which users encounter the paywall. This is where user data, gathered with the user’s consent, of course, becomes your best friend.

Here are some key factors to consider –

  • Demographics: Age, location, and even income level can influence how users perceive a paywall. For example, a younger audience might be more receptive to freemium models with in-app purchases, while an older demographic might prefer a clear and concise value proposition before they decide to commit to a premium subscription. Knowing your target audience allows you to tailor the paywall's language, visuals, and offers to resonate with their preferences.
  • In-app behavior: This is a goldmine of information. How often do users engage with your app? What features do they use the most? Do they primarily access the app on their mobile phone or laptop? By analyzing this data, you can understand user needs and pain points. For instance, a user who frequently uses the social features of an investment app might be more receptive to a paywall highlighting exclusive subscriber-only discussion forums.

The user journey matters

A user's journey within the app is another critical piece of the puzzle. People don't just appear in your app fully ready to convert to paying subscribers. They go through distinct stages, each with unique needs and expectations.

Here's how you can tailor your paywall experience to each stage in the user journey –

  • New users: They're curious and want to understand the app's core value proposition. Focus the paywall on showcasing the app's essential features and benefits. Offer a free trial or freemium model to allow them to explore the app's functionalities before asking a user to commit to a paid subscription. Highlight user testimonials or positive reviews to build trust and establish the app's credibility.
Flo app paywall comes with a free trial plan toggle
  • Active users: They are already engaged and appreciate your app's functionality. Now is the time to showcase premium features that address their specific needs based on their in-app behavior. Let's consider a fitness app as an example. A paywall could highlight personalized training programs or exclusive workout challenges designed by certified professionals if a user consistently uses the free workout plans.
Fitbod’s paywall highlights personalized workouts

And let’s say you know from tracking analytics that the user prefers cardio-related workouts to strength-training ones, then, offering a paywall that highlights "cardio-related" activities can help seal the deal. Such an approach demonstrates a deep understanding of a user’s current usage patterns and offers a clear path to, not only monetization for your business but also for enhancing the user’s experience.

  • Lapsing users: These are users who have downloaded your app but haven’t been using it actively for a while. The goal here is to re-engage them and remind them of the value they experienced previously. Showcase new content, features, or exclusive benefits available with a subscription. You can even personalize the paywall to reflect their past usage. For instance, a user who last opened your meditation app a month ago could be shown a paywall highlighting new guided meditations or relaxation techniques focused on managing stress – a common reason users return to meditation apps.

Device usage and user mindset

In addition to the user journey stage, the kind of device the user is using also affects how they interact with paywalls.

Let’s take a look at the popular devices –

  • Mobile phone: Users on mobile phones are often on the go, seeking quick information or bursts of entertainment. Their attention spans are typically short, so paywalls should be concise and visually appealing. Focus on highlighting the app's core value proposition and immediate benefits. Consider offering free trials or tiered subscription options to cater to users who might be hesitant about making a full commitment.
  • Laptop and desktop: Laptops and desktops provide an environment that is conducive to deeper browsing and engagement. Users here are more receptive to detailed information. Paywalls, whether for the web or a desktop app can show the advantages of premium features in greater depth. Offering free content samples or in-depth comparison articles can entice users to explore the value proposition before committing to a subscription.
  • Smart TV: The primary focus for smart TV users is relaxation and entertainment. Paywalls should be visually captivating, leveraging high-quality images or videos to grab attention. Highlight exclusive content unavailable on the free plan, such as newly released movies or curated playlists. Bundling subscriptions with other streaming services can also increase perceived value for smart TV users.

👉Read more: Paywall Placement

A/B testing for personalized paywalls

Just like with any marketing strategy, the key to successful paywalls lies in continuous testing and refinement.  A/B testing allows you to tailor your paywall experience to different user segments, devices, and journey stages.

Here's how it works –

Imagine you have two different paywall versions - one focusing on exclusive video content and another highlighting in-depth articles. You can use A/B testing to present these variations to users on different devices.

By analyzing conversion rates, you can see which version resonates better on each of your devices. Chances are, the video paywall does best on smart TV while the one with in-depth articles is better suited for a desktop app. For a deeper dive into A/B testing paywalls on mobile apps, check out our article on A/B testing mobile app paywalls for maximizing revenue and user engagement.

A/B testing can also be used to personalize the paywall experience based on a user's journey stage. A new user who just downloaded the app might see a paywall with a free trial offer, while a user who has been actively engaged for a month might encounter a paywall highlighting premium features. This targeted approach feels less intrusive and increases the chance of a conversion.

Here are some A/B testing best practices to keep in mind –

  • Focus on a single variable at a time. Isolate the impact of a specific change, like pricing tier or messaging approach.
  • Run tests for a statistically significant timeframe. Don't jump to conclusions based on small data sets.
  • Continuously iterate and improve. A/B testing is an ongoing process, not a one-time event.

Fitting paywalls to the user’s context

Monetization is crucial for subscription businesses, and paywalls are a key tool to achieve that goal. However, a paywall that disrupts the user experience is more likely to drive users away than towards subscriptions. The key lies in a user-centric approach – i.e. delivering personalized paywalls that resonate with individual needs and context.

Unlocking this strategy starts with understanding your users. Analyze user data to see where they come from, what devices they use, and how they engage with your app. Knowing their journey stage – whether they are new users or long-time engaged users – is also essential. This data empowers you to craft the right message, design, and timing for your paywalls.

A/B testing is your next step. Test different paywall variations to see which ones convert best on specific devices and in different user contexts. By iteratively refining your approach, you can create frictionless paywalls that seamlessly guide users toward subscriptions.

Ready to build and iterate on your paywalls? Nami ML can help! Schedule a free consultation with our experts or sign up for a free trial of our paywall builder. Start creating and testing personalized paywalls in minutes.


       

       if(window.strchfSettings === undefined) window.strchfSettings = {};
   window.strchfSettings.stats = {url: "https://nami.storychief.io/en/fitting-paywalls-to-user-context-a-guide-to-driving-conversions?id=1903370850&type=26",title: "Fitting Paywalls to User Context – A Guide to Driving Conversions",siteId: "4443",id: "51b60849-ff21-4408-b48f-9543da3cae59"};
           (function(d, s, id) {
     var js, sjs = d.getElementsByTagName(s)[0];
     if (d.getElementById(id)) {window.strchf.update(); return;}
     js = d.createElement(s); js.id = id;
     js.src = "https://d37oebn0w9ir6a.cloudfront.net/scripts/v0/strchf.js";
     js.async = true;
     sjs.parentNode.insertBefore(js, sjs);
   }(document, 'script', 'storychief-jssdk'))
   

   

Written by
Dan Burcaw
6 Nov

Rewarded Video to Unlock Subscription App Opportunities

Learn how Rewarded Video can help subscription apps monetize non-subscribers, while nudging them one step closer to subscribing.

The primary monetization goal of subscription apps is to convert users into paying subscribers. Of course, not every user who installs will convert.  That’s where Rewarded Video comes in.

Rewarded Video for subscription apps is great new opportunity to monetize non-subscribers, while nudging them one step closer to subscribing.

In this article, we’re going to discuss:

  • What is Rewarded Video?
  • How Rewarded ads can be used in subscriptions apps
  • How to get started with Rewarded access

What is Rewarded Video

Rewarded Video is a type of mobile ad unit where the user watches a full-screen video advertisement in exchange for a reward. Commonly the ads are promoting other apps and providing the user a simple call-to-action to download that app.

rewarded video ad unit

Rewarded Video ad units are non-skippable, so users need to stay engaged for the duration to receive the reward. According to Business of Apps, this ad format often commands higher eCPMs. The format is compelling for publishers and advertisers, but also for users who receive a tangible value exchange.

For example, many games use Rewarded ad units. Users are rewarded extra lives, points, and other virtual goods.

Using Rewarded Video in a Subscription App

Rewarded Video can be a useful compliment to your subscription app, especially if you offer a freemium experience.  Here are a few ways you can integrate Rewarded Video into your conversion funnel:

  1. Offer time limited premium access to users who decline your onboarding paywall. This is a great opportunity to expose them to your premium experience while they are most interested in your app.
  2. Offer time limited premium access to users who encounter & decline a paywall when trying to access premium content. This is a great opportunity to give users who want to see what a premium content or feature is about a taste even if they aren’t ready to pay.
  3. Prompt or surface the Rewarded opportunity to (certain) non-subscribers. If a user is using your freemium app a lot, but continues to decline your premium offers maybe it’s time to offer them a different route to (limited) premium access.
  4. Send an Email or Push campaign to deep link target users to the Rewarded  offer. This use case is a bit aspirational. The Email or Push marketing system would need to know that the Rewarded ad inventory will exist for the user if they engage with the message and deep-link into the app.

👉Read more: Let Your Fans Support Your App with a Tip Jar

Rewarded Access for your Subscription App

Adding Rewarded Video to your subscription app requires some product decisions as well as the right infrastructure.  

For product, consider the following:

  • Which users should get a Rewarded offer? For example non-subscribers who don’t convert from a subscription paywall.
  • When and how should those users receive the offer? For example, do you prompt them or surface the rewarded opportunity contextually in the app? reminder, even if you want to offer a Rewarded Video to a user, there has to be inventory via the ad partner. You experience needs to only offer the Reward if one is truly available from the ad SDK.
  • How much premium access (duration) should a reward be worth? For example, is the successful completion of a 15-30 Rewarded Video an hour of access? 3 minutes of access? 1 day of access?  Think about how much is enough to give them some exposure but not too much that they will never become a paying subscriber.

For infrastructure, you need two components to deliver this experience:

  • An Ad Partner with Rewarded Video ad unit. All the large mobile ad players including AppLovin and ironSource support the Rewarded Video ad unit via their mobile SDKs. Additionally, if you’re using either for mediation, you can improve the ad unit fill rate and eCPM.
  • An Entitlement Engine. Premium access is granted based upon a successful subscription in-app purchase.  To unlock premium access using another mechanism, such as watching a Rewarded Video, your app needs to abstract access control beyond the IAP product.

Rewarded Access Made Easy with Nami

This sounds like a lot, but fortunately we provide an out-of-the-box solution to make this super easy. Nami provides the Entitlement Engine. Nami also provides integrations with Rewarded Video ad solutions.

Integrations with AppLovin and ironSource offer a Rewarded premium access experience that is easy.  It requires minimal setup, limited client-side implementation steps, and no additional backend server-side. You even control how many minutes of premium access a reward is worth from the Nami Control Center.

👉Read more: Promotional In-App Purchase Best Practices

Final Thoughts

Monetization in the app economy is not easy. Rewarded Video offers app publishers another opportunity to monetize users.  For subscription apps in particular, this is a powerful way to nurture freemium users towards your premium experience while also generating some incremental revenue.

To experience Rewarded access in a subscription app, check out Serenity Sounds. To be offered Rewarded access, first try to access a premium sound (anything but the first row). You will be prompted to subscribe  via the paywall sheet.

If you dismiss the paywall without subscribing, you may be prompted if a Rewarded Video is available.  Alternatively, navigate to Settings (the gear icon) to see if a Rewarded promotional unit shows up. In either case, watch the reward to completion to receive 1 hour of access to the premium sounds.

Do you have a subscription app and are interested in adding a Rewarded experience? If so, we’d be happy to show you how it works and talk about how Nami can help.


       

       if(window.strchfSettings === undefined) window.strchfSettings = {};
   window.strchfSettings.stats = {url: "https://nami.storychief.io/en/rewarded-video-subscription-apps?id=1460241903&type=26",title: "Rewarded Video to Unlock Subscription App Opportunities",id: "51b60849-ff21-4408-b48f-9543da3cae59"};
           (function(d, s, id) {
     var js, sjs = d.getElementsByTagName(s)[0];
     if (d.getElementById(id)) {window.strchf.update(); return;}
     js = d.createElement(s); js.id = id;
     js.src = "https://d37oebn0w9ir6a.cloudfront.net/scripts/v0/strchf.js";
     js.async = true;
     sjs.parentNode.insertBefore(js, sjs);
   }(document, 'script', 'storychief-jssdk'))
   
   

Written by
Dan Burcaw
6 Nov

Monetizing a SwiftUI App: IAP & Subscriptions

We shipped a new SwiftUI app, offering a lifetime IAP and two subscriptions plans powered by Nami. See how to do it.

We decided it was time to build and ship a brand new app using SwiftUI to experience first hand the latest from Apple.

The app, now available on the App Store, is called Serenity Now.

It’s a simple audio player with a SwiftUI interface and AVFoundation under the hood. The app is filled with a collection of sounds for focus, relaxation, and better sleep.

👉Read more: Adding In-App Purchases to SwiftUI Apps

App Monetization Goals

We’re in the monetization business, so we set out to implement our own Nami SDK to offer IAPs and subscriptions.

Here are the three products we want to offer:

  • Lifetime Access - $49.99 for life (only available as a launch exclusive)
  • Monthly Subscription - 3 day free trial, then $3.99 / month
  • Yearly Subscription - 1 month free trial, then $39.99 / year

Users who buy one of these products gets access to our Serenity Now Premium features. Those features include:

  • Premium-only sound collections - Nature, Uplifting, Water & Sleep
  • Premium controls -  Repeat & AirPlay
  • Ad-free experience

We want users to encounter our paywall during the app experience in three different places:

  • First Launch - The first time the user launch the app
  • Gated Content - Upon tapping a content tile that requires premium access
  • Marketing Tile - Tapping the premium access marketing tile in Settings

Now that our goals are clear, let’s see what it takes to accomplish.

The SwiftUI Lifecycle & SDK Initialization

SwiftUI apps don’t use the the AppDelegate we have all come to know from years of building iOS apps. Instead, the entry point for SwiftUI apps is a struct conforming to the App protocol.  

That protocol has one requirement, which is the implementation of a property called body. Digging into the specifics of body is outside the scope of this article, but suffice it to say that is where you’ll kick off your app’s user interface.

For our purposes, we need a place to configure the Nami SDK. It turns out, we can provide a custom init() method on our App struct for this purpose.

Here we setup our NamiConfiguration object with our app’s unique appPlatformID (found in the Nami Control Center > Integrations > [your Apple App Store integration]

Setting up an ObservableObject to Track Purchase State

We will need to monitor changes to the the entitlements a user has access to. A change may occur if they buy one of our IAP products, or if they have a subscription that expires.

In Serenity Now, if a user buys any one of the three IAP products, we grant them access to an entitlement called premium_access.  

In SwiftUI, we can monitor for user entitlement changes by setting up an ObservableObject. Specifically,  we need to register with the Nami SDK’s registerEntitlementsChangedHandler callback to update our ObservableObject’s premium var.

Since premium has a @Published property wrapper, any SwiftUI view’s body will be re-invoked any time the value changes.

This is exactly what we want. If a user buys one of our products, we want any of the SwiftUI views that rely on the value of premium, to be updated. Concretely, this means any view that gates access based upon the premium_access entitlement will update if the value changes.

Paywall Use Case: Initial App Launch

Next, we want to show our paywall the first time the user launches the app.

Serenity Now app paywall

In our main SwiftUI view, SerenityNowHome, we run some code in .onAppear that checks UserDefaults for the value of a key didLaunchBefore.  If the value is false, it’s the first launch of our app so we tell the Nami SDK to show a paywall if NamiDataSource’s premium var is False.

Paywall Use Case: Gating Premium Content

Next, we want to gate access to certain premium content in our app.

Gating premium access with Nami

If the user does not have access to the premium content (e.g. NamiDataSource’s premium var is False), we want to present the paywall. Otherwise, we want to show the SwiftUI with the relevant content.

Paywall Use Case: Premium Marketing Tile

Finally, we want to give users a way to access our paywall from a marketing tile in the Settings section of our app.

Providing a premium upsell banner in SwiftUI

In our Settings view, if the user does not have premium access (via our NamiDataSource), we show our NamiUpsellBannerView. If the user taps on it, we show our paywall.

If the user does have premium access, we instead show a link to Manage subscription which takes the user to the system Settings.

👉Read more:What’s New with In-App Purchases at WWDC 21

Final Thoughts

There is much more we want to do with our SwiftUI app and some advanced use cases we want to discuss in future blog posts.  For now, we hope this article shows how is it is to get up and running with some very common use cases for selling IAPs and subscriptions.

You may be wondering about the paywall view itself. The paywall was created via Nami’s no-code paywall designer. The Nami SDK provides a native Swift that is configurable from the Nami Control Center so you can make changes instantly.

The SDK provided paywall integrates seamlessly with our SwiftUI app from both a user interface and usability perspective. If you’re interested in giving Nami a spin for your own SwiftUI app, you can create a free account here.


       

       if(window.strchfSettings === undefined) window.strchfSettings = {};
   window.strchfSettings.stats = {url: "https://nami.storychief.io/en/monetizing-swiftui-app-iap-subscriptions?id=1919917807&type=26",title: "Monetizing a SwiftUI App: IAP & Subscriptions",id: "51b60849-ff21-4408-b48f-9543da3cae59"};
           (function(d, s, id) {
     var js, sjs = d.getElementsByTagName(s)[0];
     if (d.getElementById(id)) {window.strchf.update(); return;}
     js = d.createElement(s); js.id = id;
     js.src = "https://d37oebn0w9ir6a.cloudfront.net/scripts/v0/strchf.js";
     js.async = true;
     sjs.parentNode.insertBefore(js, sjs);
   }(document, 'script', 'storychief-jssdk'))
   
   

Written by
Dan Burcaw
6 Nov

Apple Fiscal Calendar 2022 & Developer Payout Schedule

Apple Fiscal Calendar 2022 starts on September 26, 2021 and ends on September 24, 2022. Learn how this is used for app developer payments.

Apple Fiscal calendar 2022 starts on September 26, 2021 and ends on September 24, 2022. Apple uses this calendar for the company’s accounting as well as reporting and payments due to app developers.

Here is the 2022 calendar by quarter and by period:

Apple Fiscal Calendar 2022 by Quarter:

  • Q1: September 26, 2021 - January 1, 2022
  • Q2: January 2, 2022 - April 2, 2022
  • Q3: April 3, 2022 - July 2, 2022
  • Q4: July 3, 2021 - September 24, 2022

Apple Fiscal Calendar 2022 by Period:

  • Period 1: September 26, 2021 - October 30, 2021
  • Period 2: October 31, 2021 - November 27, 2021
  • Period 3: November 28, 2021 -  December 25, 2021
  • Period 4: December 26, 2021 - January 29, 2022
  • Period 5: January 30, 2022 - February 26, 2022
  • Period 6: February 27, 2022 - March 26, 2022
  • Period 7: March 27, 2022 - April 30, 2022
  • Period 8: May 1, 2022 - May 28, 2022
  • Period 9: May 29, 2022 - June 25, 2022
  • Period 10: June 26, 2022 - July 30, 2022
  • Period 11: July 31, 2022 - August 27, 2022
  • Period 12: August 28, 2022- September 24, 2022

App Developer Payout Schedule

Apple pays developers proceeds for app or in-app purchase sales within 45 days of the last day of the fiscal month in which the transaction was completed.

Payments are made only if the following is true:

Apple consolidates proceeds so you can expect a single payment to your bank each fiscal period.

👉Read more: Accrued Revenue

Apple Developer Payout Calendar Resource

Here is an online Apple payout calendar resource you can bookmark that is updated for the current fiscal year. It’s also available in an downloadable PDF format.


       

       if(window.strchfSettings === undefined) window.strchfSettings = {};
   window.strchfSettings.stats = {url: "https://nami.storychief.io/en/apple-fiscal-calendar-developer-payout-schedule?id=1730333766&type=26",title: "Apple Fiscal Calendar 2022 & Developer Payout Schedule",id: "51b60849-ff21-4408-b48f-9543da3cae59"};
           (function(d, s, id) {
     var js, sjs = d.getElementsByTagName(s)[0];
     if (d.getElementById(id)) {window.strchf.update(); return;}
     js = d.createElement(s); js.id = id;
     js.src = "https://d37oebn0w9ir6a.cloudfront.net/scripts/v0/strchf.js";
     js.async = true;
     sjs.parentNode.insertBefore(js, sjs);
   }(document, 'script', 'storychief-jssdk'))


   👉Play Store Developer Payout Schedule
   

Written by
Dan Burcaw
6 Nov

App Store Receipt Verification Tutorial: The Basics

Server side validation of Apple App Store receipts can be tricky. We show how to build a simple server to handle the basics to verify receipts.

One of the more tricky parts of adding in-app purchases to your Apple App is verifying receipts on a server.  Apple strongly recommends that you use a server to parse and validate receipts.  This can helps to reduce the risk of fraud.  But how do you handle things like the call to verifyReceipt or SKReceiptRefreshRequest?  We’ll break this all down by showing you how to create a basic server to do iOS receipt validation.

Apple’s StoreKit framework provides a mechanism for selling in-app purchases or subscriptions through the App Store.

An essential artifact, the App Store receipt, is used to verify purchases and understand purchase activity. In this multi-part series, we will go beyond Apple’s documentation to demystify the receipt by coding a simple Python receipt validation script then progressively building out a server-side receipt validation app using Python, Flask, and Docker. This will make it easy for you to modify and deploy to a cloud service like AWS, GCP, or Azure.

Before we jump into the Python, let’s quickly talk about how to access the receipt on the client-side.

👉Read more: iOS App Shared Secret

Accessing the Receipt from your App

The primary way you will access an App Store receipt is from your app code.

From your Xcode project, you can use the Bundle.main.appStoreReceiptURL to access the Base 64 encoded receipt data.

Here’s an example:

The code above is not guaranteed to return a receipt. Whether a receipt is returned depends on the app build:

  • Debug or Ad-Hoc builds - The receipt will only exist after a test in-app purchase takes place.
  • App Store distribution - The receipt is created when you app is downloaded, even if it is free. Practically speaking, this means your code will always find a receipt if the user downloaded the app from the App Store.

Now that you know how to retrieve the encoded receipt, next we’ll talk about receipt validation.

Choosing a Receipt Validation Approach

Now that you know how to retrieve the encoded receipt, next you need to validate it.

It’s possible to validate a receipt from the client-side or the server-side. Server-side receipt validation is more complicated, but the benefits are numerous. Especially if you offer auto-renewing subscriptions, server-side validation is strongly encouraged. You and read more about choosing a receipt validation technique from Apple’s documentation.

An App Store receipt provides a record of the sale of an app or any purchase made from within the app, and you can authenticate purchased content by adding receipt validation code to your app or server. - Apple Developer Documentation

For this series, we’re going to employ server-side receipt validation. To do that, we're going to lean on Python, Flask, and Docker to consume an encoded receipt passed up from your app’s client code. Then, we’ll dig deeper into interpreting the decoded receipt, as well as what response to send back to your client.

If you’re ready to head straight into the details of a decoded receipt, jump to our definitive guide, an element-by-element breakdown of a decoded receipt.

First, let’s build a rudimentary script to to better understand the receipt verification workflow.

Building a Simple Command Line Receipt Validator with Python

Apple provides a verifyReceipt service to be used for server-side receipt validation. The basic request and response pattern for this service is pretty straightforward, which we can demonstrate with a simple Python CLI script that does the following:

  1. Load a encoded receipt from a local file
  2. Send a validation request to verifyReceipt
  3. Print the receipt validation status

Let’s get started!

We will be using Python 3 with standard libraries, so the first thing we need to do is import the modules we will need.

Next, we need create a global variables for the verifyReceipt endpoint. There are actually endpoints: Sandbox (sandbox.itunes.apple.com) & Production (buy.itunes.apple.com). Our script will support receipts from both environments, so let’s set global variables defining each endpoint.

To determine which endpoint needs to be used, you need to know what kind of app build was used to make the purchase.

  • Debug & Ad-Hoc builds - Generates Sandbox receipts
  • TestFlight or App Store builds  - Generate Production receipts

Since this script will take in command-line arguments, let’s create a simple method to handle sending the verify receipt request to Apple. Our method will accept several arguments including whether or not we should use the Sandbox endpoint.

Best Practice: Apple recommends first sending a receipt to Production. If the receipt is for Sandbox, the response will contain a status field with the value 21007. This is your signal to try the Sandbox endpoint instead.

Next, we need to construct a valid requestBody which consists of a JSON data structure contains the Base 64 encoded receipt and a password field which is required for auto-renewable subscriptions. To locate your app’s hexadecimal shared secret via App Store Connect, check out this guide.

Now we are ready to send the HTTP POST request to Apple.

If the request was successful, you will receive a HTTP 200 OK response code. This means we can expect to receive a JSON responseBody.  The first thing we need to inspect from the responseBody is the status field. If status is 0, the receipt is valid and many other fields will be present in the responseBody as well.  We’ll dive deeper into the various elements of the receipt later in this series.

For now, we will use the status value to print a message explaining whether the receipt was validated or not.  Just in case we don’t receive that HTTP 200 OK we were expecting, we’ll also catch and print any unexpected HTTP response codes here as well. In production, you can expect to see non-200 responses from Apple so you will need to add logic to handle this and retry if need be.

Here are the most common status values you will encounter:

  • 0 - The receipt is valid
  • 21002 - The encoded receipt passed in to the requestBody’s receipt-data property is malformed
  • 21004 - The shared secret provided in the requestBody’s password property does not match what on file with Apple
  • 21007 - The receipt is from the Sandbox environment, but it was sent to the Production verifyReceipt endpoint
  • 21008 - The receipt is from the Production environment, but it was sent to the Sandbox verifyReceipt endpoint

There are others which are much more rare that you can read about here.

Now we’re ready to prepare our command-line arguments. We expect a file containing an encoded receipt to be passed to this script. If we don’t at least see one command-line argument, let’s print a helpful message.

Let’s try to read in the encoded receipt data from the file path provided in that first argument.

We need to see if any optional command-line arguments were provided. This code supports a --secret argument to pass in the hexadecimal shared secret discussed previously. Additionally, --use_sandbox tells the script to use the Sandbox verifyReceipt endpoint. Otherwise, it will default to Production.

Finally, we construct our verify_receipt method call.

You now should have a good sense for what’s involved to send a receipt validation request to Apple and the basic response codes you can expect to encounter. Head on over to GitHub for the complete source code and examples for the Python CLI covered in this tutorial.

In the next part of this series, we dig deeper into the receipt responseBody.

Until next time, happy validating!

👉Read more: App Store Verify Receipt Definitive Guide

Written by
Dan Burcaw
5 Nov

How to Handle Error Code 1 on Google Play

Error Code 1, also known as User Canceled, occurs when a user actively backs out of an in-app purchase or subscription flow on Google Play. This is a common issue developers encounter during user testing or in real-time use, and while it’s not an error in the app’s code, it’s critical to handle this response to ensure a smooth user experience. Understanding how to address this error can help retain users and provide a seamless purchasing experience.

What Causes Error Code 1?

Error Code 1 is triggered by user action—specifically, when the user decides not to proceed with the purchase. This can happen for various reasons, such as changing their mind, encountering issues with the payment method, or facing unexpected charges. While this error does not indicate a bug, it’s important to handle it correctly to offer an intuitive user experience and potentially encourage the user to try again.

By anticipating why users might cancel, developers can refine the user journey and minimize the occurrence of this code.

Common Scenarios for Error Code 1 - User Canceled

Error Code 1 often arises in the following situations:

  1. User-Driven Cancellations: The user decides to cancel the transaction, often by pressing the back button or closing the purchase screen.
  2. Confusing Purchase Flow: If the purchase flow is not intuitive, users may abandon the process due to confusion or frustration.
  3. Unexpected Charges: Users may see a higher-than-expected price due to additional taxes or fees, leading them to cancel.
  4. Testing Scenarios: During testing, developers or QA teams may cancel transactions intentionally, which leads to this error.

Best Practices and Solutions for Handling Error Code 1

Solution 1: Implement a Cancellation Callback to Handle User Cancellations

  • Purpose: Detects when a user cancels and triggers appropriate in-app responses to guide them back to the purchase flow.
  • Steps:
  1. In the billing API, implement a cancellation callback to identify when the User Canceled response is received.
  2. Provide the user with a gentle message, like “Purchase was canceled. Would you like to try again?”
  3. If they opt to retry, reinitialize the purchase flow.
  • Result: This approach helps retain user interest and makes it easy to re-attempt the purchase.

Solution 2: Simplify and Streamline the Purchase Flow

  • Purpose: A simplified and intuitive purchase flow can reduce confusion and make it easier for users to complete transactions.
  • Steps:
  1. Ensure that the purchase flow is simple, with clear steps and minimal screens.
  2. Avoid additional steps that may delay the purchase or cause users to reconsider.
  3. Provide clear prompts and messages to guide users smoothly through each stage.
  • Result: A clear flow reduces abandonment rates and enhances the user experience during purchases.

Solution 3: Display Transparent Pricing Information Upfront

  • Purpose: Displays all potential charges early to prevent users from being surprised by the final price.
  • Steps:
  1. Include transparent information about additional fees or taxes in the initial purchase flow.
  2. Provide a preview of the total price to avoid unexpected costs at the payment stage.
  • Result: Transparency in pricing can reduce user cancellations due to unexpected charges.

Solution 4: Use Soft Reminders to Encourage Purchase Completion

  • Purpose: If a user cancels due to hesitation, a gentle reminder can encourage them to complete the purchase later.
  • Steps:
  1. If the user cancels, store their place in the purchase flow (if appropriate).
  2. Send a non-intrusive reminder after some time, prompting them to complete the purchase.
  3. Provide additional context or offer to enhance their interest in completing the transaction.
  • Result: Thoughtful reminders can bring users back to the purchase flow without being disruptive.

Solution 5: Gather User Feedback on Purchase Cancellations

  • Purpose: Helps identify common reasons for cancellations, enabling developers to improve the purchase experience.
  • Steps:
  1. Prompt users with an optional feedback form if they cancel, asking what prompted them to exit the purchase.
  2. Use feedback to adjust the purchase flow, addressing any common concerns or issues.
  • Result: Feedback can help refine the purchase process, leading to higher conversion rates and fewer cancellations.

Conclusion

Error Code 1 - User Canceled, is a common response that stems from user decisions to back out of the purchase process. By following these best practices—implementing cancellation callbacks, simplifying the purchase flow, displaying transparent pricing, using soft reminders, and gathering feedback—developers can improve the purchase experience and reduce cancellations.

Nami’s low-code solutions make managing and optimizing in-app purchases seamless, allowing you to avoid complex purchase flow setups and focus on delivering a frictionless app experience. Learn how Nami can handle in-app billing for you at NamiML.