DEV Community: Surik Sarkisyan

What does restore purchase mean?

Surik Sarkisyan — Sun, 23 Oct 2022 20:20:15 +0000

When users purchase non-consumables, auto-renewable subscriptions, or non-renewing subscriptions, they expect them to be available on all their devices and indefinitely.

For the cases when a user upgrades to a new phone or reinstalls the app, you should provide them with UI functionality for restoring purchases. This allows them to regain access to any previously purchased content without paying again. But how can you create the capability and ensure it works across both iOS and Android?

In this article, we will explore what does restore purchase mean, how to configure it on iOS and Android, and the primary differences between them.

What does restore purchase mean?

The restore purchase capability is a functionality (most commonly seen as a “Restore Purchase” button) that enables app users to maintain access to subscriptions and other in-app purchases without going through the purchase process again. This mechanism allows your users to restore purchases manually.

This method is Apple’s recommended approach to restoring purchases. However, if you enable this automatically, your users will be shown a login screen that interrupts user flow – which is anything but user-friendly.

In case you have an internal authorization logic that allows you to manage access without prompt screens, you can avoid placing this “Restore Purchase” button. However, the restore button is still the most common practice. This button should trigger the specific Restore method, which will unlock the needed permissions for your users.

Cases for restoring purchase

Our recommendation is to have this button by default. Why? Having a restore purchase feature set by default could be useful for your user:

If the user has multiple devices signed in to the same account
If the user upgraded their device
If the user reset their device to factory settings
If the app was deleted and reinstalled on a device

What products could be restored?

There are 3 types of In-App Purchases that can be restored:

Non-consumables: a type that customers purchase once. They don’t expire.
Auto-renewable subscriptions: services or content that customers purchase once and renew automatically on a recurring basis until customers decide to cancel.
Non-renewing subscriptions: services or content provide access over a limited duration and don’t renew automatically. Customers can purchase them again.
Consumables purchases are not applicable for restoring as they are associated with the account. For example, if a user previously purchased “coins,” these purchases are connected to his account, and there is nothing to restore from StoreKit or Google Play Billing Library. To learn more about this process, check out our guide on how to set up consumable and non-consumable purchases.

How to configure restore purchases on iOS?

In most cases, restoring purchases on iOS only requires you to refresh the app receipt and redeliver the products listed on the receipt. The refreshed receipt contains a record of the user’s purchases in this app from any device the user’s account is logged into. To restore purchases, use native StoreKit methods. In this guide, we’ll explore the StoreKit method as the most commonly used. We are excited by the potential of StoreKit 2, so you can learn more details about it in this the following article.

Use SKPaymentQueue restoreCompletedTransactions() to restore non-consumables, non renewable, and auto-renewable subscriptions. StoreKit notifies the app’s transaction observer by calling paymentQueue(_:updatedTransactions:) with a transaction state of SKPaymentTransactionState.restored for each restored transaction. If restoring fails, see restoreCompletedTransactions() discussion for details on how to resolve it.

If you use Qonversion to manage your in-app subscription, call this method:

Qonversion.restore { (permissions, error) in
  if let error = error {
    // Handle error
  }
  if let permission: Qonversion.Permission = permissions["plus"], permission.isActive {
    // Restored and permission is active 
  }
}

How to configure restore purchases on Android?

When compared to Apple, Google doesn’t have a specific process for restoring purchases. As Google mentions, the history of purchases is available in Google’s cache, so users receive all associated permissions automatically. From our experience, it would be better to consider restoring purchase flow, as Google’s cache could consist of unactual information or could be cleaned.

To restore Google’s purchases, use this method:

public abstract void queryPurchaseHistoryAsync (QueryPurchaseHistoryParams queryPurchaseHistoryParams, 
                PurchaseHistoryResponseListener listener).

There you get the items that are purchased, and that`s it. Take note that Google returns just the last purchase from each Product.

If you use Qonversion to manage your in-app subscription, call this method:

`
Qonversion.restore { weak self in
if let error = error {
// Handle error
}

if let permission: Qonversion.Permission = permissions["plus"], permission.isActive {
// Restored and permission is active
}
}
`

Conclusion

In this article, we explored what does restore purchase mean and the flow on how to configure restore purchases on iOS and Android. By implementing this feature, you can help customers continue their paid services with ease – and keep positive user reviews coming!

Want to learn more? We know a thing or two about in-app purchases, as Qonversion provides a complete cross-platform infrastructure that allows you to create and restore purchases, validate receipts, and provide your app with an accurate subscription status without the need to build your server.

So if you’d like to learn more about it or have any questions, feel free to contact us anytime. We’d love to help you discover how to build better subscription experience with Qonversion!

How to send in-app subscription events to Firebase, Google Analytics, and Google Ads

Surik Sarkisyan — Sun, 16 Oct 2022 15:56:24 +0000

Google provides massive user acquisition opportunities for subscription apps. Using Google’s App Campaigns you can promote your app across Google Search, Google Play Store, YouTube, Discover on Google Search, and the Google Display Network. Besides user acquisition, Google’s Firebase and Google Analytics provide a set of tools to manage and grow your product. This includes advanced A/B testing, push notifications, and analytics.

But to be able to truly leverage Google’s ecosystem, a subscription app needs to send accurate in-app subscription data to Google, including data on subscription renewals and trial-to-paid conversions.

For example, though Google’s machine learning does most bidding and performance optimization in Google App Campaigns, it still needs correct revenue data to do so effectively.

This article covers how to set up conversion tracking for subscription apps with Firebase. The data from Firebase can be used everywhere on Google’s platform, from A/B testing in Firebase to campaign optimization on Google’s App Campaigns. Additionally, we will take a closer look at how conversion tracking affects your Google App Campaigns.

Google Analytics for Firebase SDK

Firebase Google Analytics is a free app measurement solution that provides insights on app usage, user acquisition, and engagement. Google recommends using this solution as it is most accurate, so if you’re using Google Ads SDK, please consider switching your tool to Firebase.

When SDK is in place, you’ll automatically receive a number of events that could be used as conversion events (goals) for your Google Ads campaigns.

However, there are just a few predefined events that make sense for subscription apps:

app_store_subscription_renew
app_store_subscription_convert
app_store_subscription_event_started (Android only)
app_store_refund (Android only)
in_app_purchase

As you see, the number of subscription events to track is very limited.

Firebase Integration: How to send subscription events to Firebase and Google Analytics

Qonversion enriches Firebase data with subscription revenue events, including purchases, trial conversions, subscription renewals, and even refunds. This allows you to match your users’ behaviour with their payment history in Firebase, empowering your user acquisition and product decisions. Qonversion sends events server-side, which means that renewals and cancellations are sent to Google Analytics in real-time, even if the customer doesn’t open the app. And even more importantly, implementation takes about 20 minutes.

Firebase track install, In-app purchases and subscriptions events iOS, Android.

To send subscription events to Firebase, you need:

Set up the Google Analytics for Firebase SDK
Set up Qonversion SDK
Send firebaseAppInstanceId to Qonversion using User Properties.

if let appInstanceID = Analytics.appInstanceID() { Qonversion.setProperty(.firebaseAppInstanceId, value: appInstanceID) }

Configure the Firebase Integration 4.1. Copy your Firebase App ID and Measurement Protocol API secret from the Google Analytics Console: Admin → Data Streams → Select existing or create a new stream for your App.

4.2. Navigate to the Tools → Integrations section in your Qonversion account.

4.3. Choose your platform (IOS or Android) and click the Add new + button and select Firebase.

4.4. Provide the API Secret and App ID copied in the first step to the corresponding fields.

That’s it! From now on, all subscription events will be visible in Firebase.

How to link Firebase Google Analytics to Google Ads

This step is necessary if you’d like to optimize your Google Ad campaigns based on Firebase conversion tracking events.

To successful setup, you need to perform four steps:

Firebase => Project Settings
Click Integrations tab
Link Google Ads to Firebase project
Enable events as conversions: On the Events tab, in the row for Qonversion events, turn on the switch in the Mark as conversion column. You can have a maximum of 15 conversion events per app in Firebase. Once an event has been enabled as a conversion, it is available in Attribution > Conversion Events. Attribution reporting begins for that event at the time you enable it as a conversion.

The data from Qonversion Firebase Integration unlocks new capabilities for Google App Campaign optimization for subscription apps. Let’s take a deeper look.

What Google App Campaigns are

Google App campaigns are user acquisition channels that allow you to promote your app within the Google Network – on Youtube, Discover, Search, Google Play, etc. Unlike most Google Ads campaigns, you don’t need to create individual ads for each campaign. You only need to upload the set of assets: text, images, videos, and a starting bid and budget. Google will automatically design different ad variations across different formats and networks. Google Ads will test different combinations and show better-performing ads more often, with no extra work on your part.

There are three main types of Google App Campaigns:

Google App Campaigns for installs.
Google App Campaigns for pre-registrations.
Google App Campaigns for engagement.

The insights of this article could be the most useful for Google App Campaigns for Engagement and Google App Campaigns for Installs optimization. You can check more details on Google App Campaigns here.

How to optimize Google Ad based on Firebase conversion events data

Google App Campaigns optimization by conversion event

You can set the primary conversion event for your Google App Campaign. Google Ads will automatically use this data to learn to optimize your ads, using this parameter to get you the best number of conversions and to optimize your set cost-per-action bid.

Open the settings of your Google App Campaign.
Choose which in-app actions (conversion event) you want to optimize your campaign for, and then enter a target cost per this action (target CPA).

That’s it! Now Google Ads has enough data to learn to optimize your campaign by specific metrics: trial to subscription, or subscription to renew, etc. The fill list of metrics that you could optimize your campaigns for is here.

Google App Campaigns optimization by the audience

You can create audience segments in Firebase using any combination of events and user properties (for instance, people from UK that subscribed to your app for the first time).

Then, you could apply your segments for a particular App Campaign. Segments based on mobile app data can be targeted by Search, Display, and Video campaigns.

Create a segment in Firebase.
Make sure that your Firebase account is linked to Google Ads.
Open the settings of your Google App Campaign.
Choose the Target Audience Segment.

That’s it! Now Google Ads has enough data to lern to optimize your campaign for the specific audience – whether they are new or returning users, or people from specific territory.

Conclusion

In this article, we explored how Qonversion Firebase Integration allows you to enrich Firebase data and improve the strategy of your user acquisition campaigns. In the following article, we’ll dive deeper into how this integration enables you to attribute user acquisition costs within other Ad Networks outside Google – AdColony, IronSource, Vungle, and others.

SKErrorDomain Code=0. What is it and how to fix it?

Surik Sarkisyan — Mon, 10 Oct 2022 08:30:06 +0000

Domain=SKErrorDomain Code=0 “(null)” is one of the more common errors that you may struggle with while processing in-app purchases. This error can occur in both production and sandbox environments and affects the fail to success payment ratio of your app.

Though the reason for this error is more likely to be on the App Store’s side, there still are a few things to try.

In this article, we’ll give you a brief overview of the possible reasons for the error, and what you could test to prevent it from happening.

SKErrorDomain Code=0 in the sandbox environment

When SKErrorCode=0 occurs while in the sandbox environment and not in the production environment, it could be related to issues with the sandbox on Apple’s side and could potentially affect the make payment call and the /verifyReceipt endpoint, although it won’t do this in production mode.

Things you can check:

Test your in-app purchases with a real device, not in the simulator
Check your in-app Product ID
Create a new sandbox test account on the App Store, then logout from all other accounts, and then test it with the new sandbox test account
Check whether your in-app purchases are configured correctly on App Store Connect and have the following statuses: Ready to submit or Ready for sale.
Check if your app bundle ID matches the bundle ID from App Store Connect where the purchases were created.
Add Localisation (Subscription Display Name and Description) to the product. The hypothesis is that there is no obvious way to see this from the error and therefore you may quickly miss it when you are preparing placeholders for future In-App Purchases. However, it seems that Apple should mention this in its documentation and implement an error code that gives a warning about any missing metadata.
Reboot/Reset the device
Check that you agreed with the latest versions of Apple’s policies

If you have tried everything from the list above, then it means that the issue is on the App Store’s side and you should follow the information on Apple’s status page or submit a bug report.

SKErrorDomain Code=0 during the review process

If you have difficulties during the app review process, then you will have to ask the reviewer to retry the purchase. Also, Apple’s engineers highlight that App Review should not see any issues with sandboxes as they use special accounts for the review process. So if your app was rejected then the issue mostly probably lies elsewhere.

SKErrorDomain Code=0 in production environment

If you receive Error Domain=SKErrorDomain Code=0 “Operation could not be completed. (SKErrorDomain error 0.)” in the production environment, try the following:

Make sure you have used the correct Product Identifier. If you have, then you’ll get error 0 shortly after calling [SKPaymentQueue addPayment:], and before you get the popup asking you to confirm payment.

Try to create a new test user as your current test user might have been invalidated. This can happen if you accidentally log into the App Store with your test user. When this happens, you’ll get error 0 after entering your password to confirm the payment.

Unfortunately, not much else can be done regarding this error while in the production environment. This error mostly comes directly from Apple, and is an unknown error to do with their API. If you are using Qonversion to manage in-app subscriptions, we would also recommend checking our status page for any reported outages. Unfortunately, these errors are returned randomly and directly from Apple.

Submit a bug report about SKErrorDomain Code=0

When the issue is on Apple’s side, it can affect everyone or just some users. It’s always a good idea to submit a bug report with complete information, including a sysdiagnose archive from the device. To submit the bug report, please use Apple Developer Bug Report and follow the instructions. Before you begin, make sure you are familiar with triggering the sysdiagnose log, then follow and perform each step to replicate the problem. When the failure occurs, first, trigger the sysdiagnose profile, then wait 5 minutes before syncing the device with Apple Store and then look for the sysdiagnose archive file. While reproducing the issue, you should take screenshots showing evidence of the connection failure.

We will update this article if and when more details regarding this error become available. If you are getting other Storekit errors, then check out this complete guide on how to handle storekit errors.

What’s new in StoreKit testing (WWDC22 updates)

Surik Sarkisyan — Mon, 13 Jun 2022 07:12:57 +0000

New day, new WWDC22 session, new overview! Today we’ll walk you through the updates in StoreKit testing.

Before we move on, I’d like to emphasize that previous significant updates for StoreKit testing were introduced during WWDC20, which we’ve also covered here.

Now, it’s time to move on to the brand new updates!

What we will cover today:

StoreKit updates in Xcode 14
Advanced subscription cases
Sandbox updates

StoreKit updates in Xcode 14

During WWDC20, the StoreKit.configuration file was announced. This unlocked the capability to test in-app purchases without needing to set up the Products in App Store Connect.

This allowed you to set up in-app products directly in StoreKit.configuration file, and this local file would be the only place that contains these products and purchases.

The latest WWDC22 updates require you to create the app and products in App Store Connect. You still have an option to test your in-app purchases through StoreKit.configuration directly in Xcode without having an app in App Store Connect. The only limitation of this commonly used approach is that you will not have the chance to use a part of a new features.

You may wonder: what are the features of this and are they worth all this hassle with app creation in App Store? My answer is: absolutely!

By having an app with the products in App Store Connect, you can create a new configuration file in Xcode that will synchronise these products with those that were created in App Store Connect. Any changes that you make within App Store Connect – whether changing the title of the product or doing something else – can be synced with this Xcode Configuration file.

Additionally, you can convert this new file into the local version that won’t be synced with App Store Connect, but will give you an option to edit your products directly in Xcode. Be accurate and careful here, because this is a one-way operation. You will not have a chance to convert the local file back to the synced version. So, in order to proceed with further syncs you’ll need to create a new file. A great option is to have several StoreKit.configuration files; for instance, you could have both synchronized and local ones.

To create the new StoreKit.configuration file you should go to Xcode Menu => File => New (or lock Command + N). Then, type storekit in the search, select StoreKit.configuration file, and push the “Next” button.

Here’s a screenshot to clarify this process:

In Xcode 14 while creating this file you’ll see the checkbox that enables the syncing of in-app products with App Store Connect. To turn this option on, you need to choose the Team and App.

It will be pretty clear to you that to create the local file you should just fill the name of the file and leave the checkbox unchecked.

Once you create a configuration file, all the information about your Products begins to sync with App Store Connect. In the lower right corner, you’ll notice the indicator showing you that data downloading is in progress. Even though this job is in progress, you can still continue to work in Xcode.

Those who used to work with the local version of StoreKit.configuration will notice that the newly created file differs from the files that they used to see. The reason for this is that this local version of StoreKit.configuration is read-only. All the changes in products should be made with App Store Connect.

As we highlighted before, all the changes in products that were made in App Store Connect can be synced in StoreKit.configuration file just with one button below. Once the sync is complete, you can see the changes reflected in Xcode.

As I mentioned, this is a read-only file.

You still can easily copy the Product from this file and move it to the local StoreKit.configuration file in Xcode. To do so, right click to the Product that you’d like to copy and click “Copy”. Then choose the local file and open Xcode Menu => File => Paste (or hold command + V).

Alternatively, you can convert this synced file to the local one. You can’t undo this operation, but if necessary you can create a new synced StoreKit.configuration file. Xcode Menu => Editor => Convert to Local StoreKit Configuration.

Let’s move on to the testing.
To start this process you should choose the StoreKit.configuration file in Xcode that should be used for building the app. This is a commonly used method.

Then open Scheme Editor:

Choose the “Run” action, then “Options”, and then choose the right file in the StoreKit Configuration:

Congrats on the successful set up of your testing environment! Now you can configure your app.

One more great update for those who use SwiftUI: starting with Xcode 14, all the Products from StoreKit.configuration files will be uploaded to SwiftUI previews.

Let’s move on to the testing. As you might remember, WWDC20 introduced the Transaction Manager. You can open it by clicking on the “Purchases” icon in the debug bar.

Xcode 14 Transaction manager includes Transaction Inspector (on the right side) that displays under-the-hood details about a transaction. This is a super convenient way to check subscription statuses. For instance, here you could see the information about expired subscriptions or subscription renewals.

Also, by clicking these buttons you can move to the specific Product in StoreKit.configuration file in Xcode.

Moreover, at the bottom part of the inspector, there is a field to filter transactions. For instance, you can filter by the day of creation of the transaction or by Product ID. This significantly simplifies the way you navigate all your transactions (it is quite a daunting task, as you have all subscription renewals that may confuse your detection of which transaction entitles the feature).

Advanced subscription cases

The new version of Xcode allowed the chance to test things in a more convenient way, and to test something that was previously impossible to test. This is really exciting!

What was added:

Refund requests
Offer codes
Price increases
Billing retry and a grace period

Refund requests

As you might guess, the option to cancel the subscription directly in the app was released. It means that you can test this functionality for your app.

To show the corresponding screen you need to call just one function: refundRequestSheet(for:isPresented:onDismiss:)

The refund request sheet will appear above the view. It will include the list of refund reasons, and this list corresponds to revocationReason property in the App Store Server API.

It looks like this:

If we are speaking about the Product in App Store, you should remember that refunds can take some time to process; however, when testing with Xcode or Sandbox, a refund request will immediately refund the transaction. You could see this refunded transaction in the Transaction Inspector. You’ll see both the refund reason and the refund date there.

Moreover, you can test the refund directly in the Transaction Manager by clicking the “Refund purchases”.

We’ve described how to test refunds, but how does it look from the code perspective?

The Transaction object that is received from StoreKit consists of revocationDate and revocationReason properties. This will help you detect the refunded transactions.

For iOS and iPadOS the testing through Xcode iIs available starting version 15.2, through Sandbox – starting 15.0. MasOS in Xcode – 12.1, Sandbox – 12.0.

Offer codes

In the following example, let’s test offer codes redeem flow with the local configuration file. If you already have offer codes in App Store Connect, and you use synced StoreKit.configuration file, you’ll see these codes automatically in Xcode.

For our case: go to the local file, click the “plus” in “Offer Codes”, configure Offer Code, and click Save.

Once configured, it should be tested. The code implementation is simple in the case of refund requests. You just need to call the function: offerCodeRedemption(isPresented:onCompletion:)

Now you should see the redeem offer code sheet above your app. Only the users of your production app should enter offer code in this field. While testing with Xcode, you won’t need to enter offer code in this info, but rather only to choose the offer code from the list (as all this data is kept in StoreKit.configuration file).

It’s incredibly easy: choose the offer code, confirm the operation – and profit!

Once the offer code is successfully processed, you’ll see this transaction in Transaction Manager; all the details will be available in the new Transaction Inspector.

Let me skip the part where I explain the logic of managing this transaction, as it is quite straightforward. The only difference from managing the ordinary transaction is that you should check a few additional properties.

While managing transactions you can check the offerType property to see if there is an offer applied to the current transaction. While handling renewalInfo, use its property offerType to see what kind of offer will be present in the next renewal.

Offer codes are an incredibly valuable tool for working with users in your app. There are so many things you can achieve, from user acquisition to winning churning customers and support/loyalty programs. So it’s incredibly valuable that we now have a ability to test it.

Just to remind you, this option didn’t previously exist, even in the Sandbox!

Everything described above is available starting Xcode 13.3 and higher and iOS/iPadOS 15.4 and higher.

Price increases

As you might know from our previous overview of WWDC22, StoreKit Messages are aimed to be used to display messages from the App Store API to users. One example of such messages is a change in the app’s price. Let’s take a closer look at how we can test this scenario.

First, change the price of the Product in the StoreKit.configuration file in Xcode. Alternatively, you can choose the needed transaction in the Transaction manager and click the “Request Price Increase Consent”.

You can skip the flow of how to display the StoreKit Messages, but in this case the message will appear automatically over your app. If you’d like to avoid interrupting your user’s flow and do not want to affect user experience, you should implement the StoreKit Messages sequence the same way that you handle the transactions in StoreKit. Find these details here.

What is important is that this price-changing screen might be shown to your users several times until they consent to the new terms. In Xcode, you can manually call this screen only the needed number of times (read above). It is important to remember that the users might consent outside of the app – for instance, via email.

In Xcode, you can test this consent screen display scenario just by clicking the corresponding buttons in Transaction Manager.

Let’s take a look at the code side. As you work with the purchases in your app, you probably are already implemented Statuses.updates sequence. The only thing that you should do now is to check renewalInfo => priceIncreaseStatus property to receive the needed state. Check the expirationReason property to detect if the customer canceled the subscription after the price changed.

All this is unlocked by starting the following versions of OS:

Please consider that StoreKit Message testing on price changing is available just for iOS/iPadOS 15.4 version and higher.

Billing retry and grace period

Billing retry is where an error occurred while trying to renew a subscription, such as if a credit card is expired.

In this case, App Store will attempt to fix the billing issue to renew the subscription.

You can enable a grace period that gives your customer the ability to use your subscription for a limited period of time at the beginning of the billing retry state. In other words, this is a period for the user to solve billing retry issues, pay for the subscription, and continue to experience the app.

Let’s take a look at how to test this case in Xcode.

Choose your StoreKit.configuration file, then Editor Menu => Enable Billing Retry on Renewal. If you’d like to test the grace period, you can refer to the next point in the same menu.

For further convenience, you can speed up the subscription renewal rate from the same menu.

The next steps are straightforward. Let’s subscribe to the app then wait for the renewal period time (that you choose in the Subscription Renewal Rate menu). At the moment of renewal, you’ll see the new transaction with Billing Retry in the Transaction Manager. The Transaction Inspector will show that the transaction is in the grace period. Once the grace period expires, the transaction appears in the standard billing retry state. You can resolve the billing issue by clicking the corresponding button in Transaction Manager.

Handling billing retries and grace periods is key to retaining subscribers by reducing involuntary churn.

Now it’s time to explore how you can handle this in the code.

As the billing retry and grace period states change, the Status.updates sequence will emit a new value.

All that you should do is check, using the renewalInfo.GracePeriodExpirationDate property, whether your user is in the grace period. If so, you should grant him access as if the subscription were active. To detect whether the user is in a billing retry state, check the renewalInfo.IsInBillingRetry property.

Both of these states can be checked with state property in Product.SubscriptionInfo.Status you’d like, you can redirect your user to the App Store to fix the billing issues.

If you are using any currentEntitlement API, you’ll receive the transactions for expired subscriptions while they’re in the grace period.

In which versions is this feature available? Check the following:

So these are the exciting updates with Xcode testing! These will definitely improve the developers’ experience while working with in-app purchases.

Sandbox updates

Last but not least – the updates related to Sandbox.

What we’ll explore:

Sandbox Apple ID creation
App Store Connect API
Billing failure simulation

Sandbox Apple ID creation

To unlock the ability to test in Sandbox, you have to create a testing user.

There are several pieces of good news.

The number of fields that you should fill while creating the user significantly decreased.
You can use “+” symbol in email to prevent you from creating a new email for every user. For instance, “your_super_test+sandbox@iclod.com”
Added in-line suggestions for passwords

App Store Connect API

For the last few years, Apple engineers have added a lot of features to Sandbox per developers’ requests. The changing of the Sandbox account region and clearing purchase history is one of these.

Most of these features are available in App Store Connect or directly on the device on the Sandbox Manage Subscriptions page.

Later this year, the following Sandbox features will be added to App Store Connect API:

Query for Sandbox Apple IDs
Clear in-app purchase history
Set interrupted purchase state

These features will improve the speed of subscription testing with Sandbox accounts and add possibility of automated testing in the basic scenarios.

Billing failure simulation

Since launching in 2019, Billing Grace Period allowed developers to recover 300 million days of paid service to their customers. Soon, there will be the capability to use a new Sandbox Account Settings page to:

enable billing failure simulation for your account
test foreground and background subscription failures
verify subscription status with verifyReceipt, App Store Server API and App Store Server Notifications v2 in Sandbox.

Conclusion

With these testing scenarios, Apple explores the statuses that will affect App Store Notifications V2. This is a big topic to cover, so stay tuned for other articles!

We know a thing or two about in-app purchases as Qonversion provides a complete cross-platform infrastructure that allows you to create and restore purchases, validate receipts, and provide your app with an accurate subscription status without the need to build your server. So, If you’d like to learn more about it or have any questions, feel free to ping me in the comments.

If you'd like to learn more on how to handle StoreKit errors, please follow our guide. Also, recently I've created an article on how to solve SKErrorDomain 0, feel free to check!

WWDC22 overview: how to integrate and migrate in-app purchases to App Store Server API

Surik Sarkisyan — Fri, 10 Jun 2022 10:47:11 +0000

Hey everyone, today we’re going to continue our WWDC22 blog post series on what’s new with in-app purchases. We’ve already covered some of the updates: enhancements to StoreKit 2 and App Store Server API.

Today, we’ll focus on the next updates that were announced during the session Explore in-app purchase integration and migration. The session is divided into two chapters – App Store Server API and App Store Server Notifications Version 2.

In this article, I’ll mostly refer to the first part of the video. We’ll talk about App Store Server API – powerful, secure, and with efficient server-to-server endpoints, then we’ll explain how to migrate to it.

The main idea behind this API is pretty clear: to give you the all data you need about in-app purchases.

App Store API was introduced on WWDC 2021. These are two great sessions that I highly recommend to watch; however, they won’t affect your understanding of today’s topic.

What we will cover:

How to use the App Store Server API
How to sign JSON Web Tokens
How to verify signed transactions
How to migrate from verifyReceipt So, let’s get going!

Using the App Store Server API

In this part, we’ll cover the cases of Using the App Store Server API. Additionally, I’ll cover how to use the new API with StoreKit in different scenarios: when you need to support Original StoreKit, StoreKit 2, and both of it – for instance, if you decided to keep supporting StoreKit for users with previous iOS versions and add StoreKit 2 support for those who use updated versions of Apple OS.

Which endpoints are available with the new API?

GET /inApps/v1/subscriptions/{originalTransactionId} – get the statuses for all of a customer’s auto-renewable subscriptions in your app.
GET /inApps/v1/history/{originalTransactionId} – get a customer’s in-app purchase transaction history for your app.
PUT /inApps/v1/transactions/consumption/{originalTransactionId} – send consumption information about a consumable in-app purchase to the App Store after your server receives a consumption request notification.
GET /inApps/v1/refund/lookup/{originalTransactionId} – get a list of all refunded in-app purchases in your app for a customer.
PUT /inApps/v1/subscriptions/extend/{originalTransactionId} – extend the renewal date of a customer’s active subscription using the original transaction identifier.
GET /inApps/v1/lookup/{orderId} – get a customer’s in-app purchases from a receipt using the order ID.

The first 5 requests require originalTransactionid as an input parameter, which allows you to easily use these requests just having originalTransactionId. You can receive this parameter from receipts, signed transactions, signed auto-renewals, and notifications.

The 6th request requires orderId as an input parameter. But what is that parameter used for?

The main idea is to support and interact with your clients. When the customer makes a purchase, he receives an email with the data about the completed purchase. This email includes some details, and the orderId is one of them. This data could be received as well from a purchase history on the App Store.

Thus, when the user contacts your support team and sends a support query, he shares the orderId, and you receive the needed data through the Look Up Order ID endpoint.

It’s worth mentioning that Apple announced 3 more endpoints as well, but as we’ll explore these and other Apple notifications in future articles. For now, let’s just take a quick look and move on.

Here they are:

POST /inApps/v1/notifications/test – Ask App Store Server Notifications to send a test notification to your server.
GET /inApps/v1/notifications/test/{testNotificationToken} – Check the status of the test App Store server notification sent to your server.
GET /inApps/v1/notifications/history – Get a list of notifications that the App Store server attempted to send to your server.

How to get `originalTransactionIds` with the Original StoreKit?

When you call the endpoint verifyReceipt, you can see that in responseBody => responseBody.Receipt.In_app field you can find originalTransactionId for each user’s purchase. The same can be found in responseBody.Latest_receipt_info and responseBody.Pending_renewal_info.

Let’s take a look at what this looks like:

With knowledge of how to get the originalTransactionId from Original StoreKit transactions, let’s explore the whole flow between a customer, the App Store Server, and your server:

Obtain the app receipt on our server
Take the app receipt and call verifyReceipt with it from your server.
Get the decoded receipt in a response.
Get all of the originalTransactionIds from the decoded receipt in precisely the same ways I previously showed.
Call GET /inApps/v1/history/{originalTransactionId} with any one of the gathered originalTransactionIds.
Handle history of transactions for this user in response. These transactions include non-consumables, refunded consumables, non-renewing subscriptions, and auto-renewing subscriptions.

Then, if you want to get the latest signed transaction and signed renewal information for a specific subscription, call GET /inApps/v1/subscriptions/{originalTransactionId} with the corresponding originalTransactionId. As a result, you’ll receive the list of all signed transactions and signed renewals, which corresponds to originalTransactionId.

How to get `originalTransactionIds` with the StoreKit 2?

On the client you can get the originalTransactionIds with the following steps:

Get signed transaction from the devices that are on iOS 15 and later
Get the originalID property from this transaction

In terms of the API side – you’ll receive the originalTransactionIds on the top-level field, as described in the screenshot below. Here you’ll see an example of a signed JWS transaction, which is the data type you receive in signed transactions and in signed renewals from the App Store Server API and App Store Server Notifications.

Then, let’s proceed with the following steps:

Get the transaction on a user’s device
Send the transaction to your server
When you need to perform an operation on a subscription, such as extending the renewal date of a subscription, you can use the originalTransactionId from the signed transaction to call PUT /inApps/v1/subscriptions/extend/{originalTransactionId} endpoint and get back the data that you need. The screenshot:

How to handle `originalTransactionIds` with both versions of StoreKit?

So, we explored the ways to use the new API with the Original StoreKit and StoreKit2.

For the cases when you have to support both versions of StoreKit, the advice is quite simple: just take all the advantages of the App Store API and use them regardless of the version of StoreKit that processed the purchase.

To validate new purchases that were made with the Original StoreKit, the process is simple:

Get the receipt from a customer
Send this receipt to your server
Call verifyReceipt endpoint to receive decoded receipt
Request the status of the purchase with GET /inApps/v1/subscriptions/{originalTransactionId}
Get all signed transactions and renewals It’s essentially the same as the process described before, except that, as you might notice, the history purchase step is skipped.

That’s it for App Store API!

Signing JSON Web Tokens

JSON Web Token is needed for Apple to authenticate you when calling the App Store Server API. This token should be used as an authorization header in each of your server’s requests.
JWT consist of: header, payload, and the signature.

How to construct JSON Web Token for your app?

On the picture below you can see the structure of the JWT, header and payload.

The token itself can be divided into three parts, separated by periods:

The base64 encoded header
The base64 encoded payload
The signature, which is composed of the base64 encoded header + base64 encoded payload, signed using your signing secret.

Header

The header consists of metadata that represents the information on how to sign your data.

Pay attention to the key ID field (kid) – this is your private key ID from the App Store Connect. This key ID should correspond to the key that you use for JWT signature.

Payload

Payload keeps all the data about your application. To learn more about this field please read the official documentation from Apple.

For additional info on how to get your API key please read this article.

Once you receive all the data that you need for the JWT, you need to sign the JWT using the certificate that corresponds to the key ID.

Let’s take a closer look at an example (pseudocode). Please note that the final code will look different depending on the programming language, the chosen tools, and libraries with which you will implement it. But the logic behind remains the same.

import jwtLibrary;

var privateKey = readFile(“/path/to/private_key.key”)
var token = jwtLibrary.sign(payload, privateKey, header)
One your preferred library generates token, you can paste it into cURL that will get subscription statuses by `originalTransactionId`

This is an example:

curl -v -S -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer ${token}' \
    https://api.storekit.itunes.apple.com/inApps/v1/subscriptions/${originalTransactionId}

Don’t forget to:

replace ${token} with the parameter that you’ve generated in example above.
replace ${originalTransactionId} – the Id, with which one you’d like to get the data.

Verifying signed transactions

Let’s discuss how to verify the transactions that you receive from Apple and that were signed by the App Store.

Signed transactions are JSON and are cryptographically signed, so if someone would try to replace it between App Store and your server, you can easily detect it.

These transactions are signed in the JWS format – Json Web Signature (do not confuse this with JWT, which was discussed above). By verifying this object you receive the data from the App Store and can ensure that it was not tampered by anyone.

How can I verify a signed transaction?

Decode base64 header
By alg claim in this base64 header you could understand which algorithm you should use. It will be used for the JWS verification.
Verify certificate chain in the x5c claim Now, once we verified this data, we are on the safe side – no one tampered our data.

You can learn more about JWS here. Also, please read the App Store Server API documentation to learn more about JWSTransaction.

What is the x5c chain?

This is a chain of certificates, the successful verification of which means that the data can be trusted and is signed by Apple.

What is important for the certificate chain is the order. At the beginning you’ll get the root certificate. The root certificate may be followed by additional certificates from the chain. Each following certificate is signed by the previous one. The last certificate in this chain is referred to as the leaf certificate. The first certificate is referred to as the root certificate, and is self-signed.

This certificate should match to the root certificate you obtain from the Apple’s Certificate Authority. If it does not, then the verification chain will be defined as failed.

The last certificate (leaf certificate) is used for JWS signing.

Let’s take a look at the JWS header:

At the beginning of the first line, in the alg field, there is the name of the algorithm that is used for the JWS signing. Next, in the x5c, there is a chain of certificates listed in order.

Let’s look a bit more closely at what x5c certificate chain generation looks like.

At the beginning, we take a root certificate from the Apple’s Certificate Authority. Next, we sign the intermediate certificate. There might be several certificates in this chain, and as we discussed above, each following certificate is signed by previous one. In the example below we consider the one intermediate certificate. Then, this intermediate certificate signs the leaf certificate.

Ok, we’ve described the way this chain generates. Now it’s time to move on to the next chapter – how you can verify it.

This part is simple – you just need to reverse the process.

First, make sure that the leaf certificate is signed by intermediate one. Then, that intermediate certificate should be signed by the root certificate. And the root certificate should match the one one of Apple’s Certificate Authorities. If all steps are successful, the chain is verified and counted as valid.

Let’s discuss a specific method of chain certificate verification.

This is the command fot x5c chain using OpenSSL verification:

openssl verify -trusted AppleRootCA-G3.pem -untrusted AppleWWDRCAG6.pem leaf.pem

The command verify initiates the process of certificate verification.

With -trusted we send the certificate that we trust and that will be used for the verification of the following certificates. This should be root certificate that was obtained from Apple’s Certificate Authority.

With -untrusted we send a certificate that wasn’t verified yet, but that we’d like to verify.

As a first parameter we use the WWDR certificate that received from the Apple’s Certificate Authority and signed by root certificate. This should match to the second certificate from the x5c chain. The last parameter is a leaf certificate that was signed by the previous certificate. In case of successful verification, you’ll receive a success code, and in case of failed verification, you’ll receive an error code. If verification is unsuccessful, the data shouldn’t be used.

More information about the verify command in openssl is here.

The information on openssl is here.

Migration from verifyReceipt to App Store Server API

In this part, we’ll explore the several corner cases.

How to check the subscription status of the particular user

Previously, you had to call verifyReceipt and define the status by checking several fields from the response. Now, with App Store Server API you can call GET /inApps/v1/subscriptions/{originalTransactionId} and receive all the needed data, such as subscription status, renewal info and other pieces of data in one response.

How to receive the latest transactions of the user

The next case described is when you’d like to get the latest transactions of the user to check what he purchased, whether the subscription is auto renewed, or whether there were changes like upgrades, downgrades, or plan switches.

As in the previous example, with the previous API version you had to call verifyReceipt and get the data from the responseBody.Receipt.In_app and responseBody.Latest_receipt_info fields.

With the new App Store Server API you can refer to the GET /inApps/v1/history/{originalTransactionId} endpoint that covers all needed data.
And last but not least – the new appAccountToken field that fetches UUID. We’ve covered this field in our previous article, but just to remind you: this field lets you add the unique ID of the users from your system just to connect your user with their purchases. In the previous API version there was an analogue of this field – applicationUsername – that fetched the string, but the official documentation recommended sending UUID into this field. And once you send the UUID format string into this field, you’ll see this parameter automatically in appAccountToken. The needed value will appear in StoreKit Transaction, App Store API, and App Store Server Notifications.

Conclusion

In this article, we explored the new capabilities of App Store Server API, how to integrate and migrate in-app subscriptions into API, and how to sign JSON Web Tokens and verify signed transactions.

If you still have any questions about the logic behind these updates, please feel free to reach out to us. Qonversion provides a complete cross-platform infrastructure that allows you to make and restore purchases, validate receipts, and provide your app with an accurate subscription status without the need to build your server.

If you'd like to learn more on how to handle StoreKit errors, please follow our guide. Also, recently I've created an article on how to solve SKDomainError 0, feel free to check!

What’s new with in-app purchases: WWDC 2022 overview

Surik Sarkisyan — Thu, 09 Jun 2022 13:31:14 +0000

This Tuesday, during WWDC 2022, Apple released the latest updates for in-app purchases. A lot of great updates are still coming, but today we’ll walk you through the improvements that have already been covered: enhancements to StoreKit 2 and App Store Server API.

So, let’s get started.

New App Transaction API is released

Apple has released the new API to verify the purchases of the app. The new API aims to mitigate (or totally prevent) fraud and add more flexibility to the ways you can monetise the app and grant users access.

The new App Transaction API presents the signed information about the purchase and the device with which the purchase was made.

What you should know about the new App Transaction API

- It’s signed using JWS signature
- It replaces the app details of the app receipt from the original StoreKit API
- StoreKit validates purchases automatically
You still can create your own receipt validation flow, but you’ll need to validate a JWS signature. As Apple highlights, the process is described in the official documentation, so you can easily handle it on your own.
- StoreKit automatically refreshes transactions, but in rare cases users can do this manually.
To provide this functionality, you need to create UI capabilities within the app so users can refresh the app transaction themselves.

Why it would be better to avoid actions from your side: it’s the same story as with the old API restore function. If the user doesn’t log in and you’re trying to refresh his transaction, he will unexpectedly see the screen that prompts him to authenticate. It might be shocking for users who didn’t take any action with the purchases.

How to handle switching business models with the new App Transaction API

The new App Transaction API also allows to change your business model easily without affecting the access of existing customers.

App Transaction API allows you to receive the necessary details about the user so you can change your business model from the paid app to free with in-app purchases or subscription monetisation. Previously, you would receive these details by processing the receipt.

Let’s take a closer look.

Previously, receipts combined all the information in one section.

Like this:

Now, the information is divided into separate components in StoreKit: Transaction History and App Transaction.

The first section includes the entire in-app purchase history: the user’s latest transactions, unfinished transactions, and current entitlements. You can receive all this information on your server as well through the App Store API.

The second component, App Transaction, contains all the data you need to understand whether your user has ever purchased your app previously.

So let’s take a look at the scenario of switching your business model from the paid app to the free app with subscriptions.

Apple has provided a great example of such an app’s timeline. Let’s assume you have two users: the first one has bought the paid app (v2.5) and the second has purchased the subscription after you switched the monetisation model (v8.2).

The change in your app’s business model means that there will also be changes in your access management logic for the app.

For instance, you have several features that were previously available for all who purchased your paid app, and now these features are available as non-consumable purchases. Additionally, you’ve added some new cool features that are available with subscriptions. In this case, you should make sure that all your existing customers (v1.0 to <8.0) have access to the premium content they paid for. But you could still suggest that your user buy the new features that become available after switching the business model. Newcomers (v8.0 and higher v8.2) could purchase everything as it is.

As we mentioned previously, in this case you should distinguish your users: distinguish the ones who bought your paid app from the newcomers.

Let’s take a look at the code that will help us with it:

On the first line of this code, we get the transaction. Then you should check whether it is verified or not.

If the transaction is not verified: you can prompt your user to refresh the app transaction and restore the access, simply give the user access to the app but with minimal functionality, or suggest purchasing a subscription.

If the transaction is verified: you should determine whether this user gets the app.

App Transaction is contained in the field originalAppVersion that displays the information about the app version that corresponds to this transaction. If this version is older than the version that you’ve released your new monetisation model, you need to grant the user the needed access. If the version is newer, you should check which access you should grant to your user.

As you could see, just a few lines of code allow you to receive the verified transaction that contains all the needed details to understand which app version was purchased and when. As I mentioned, it could be possible just by processing of your receipt (that wasn’t too easy).

New Properties in StoreKit

PriceLocale

PriceLocale is now included in product. But what has changed?

Previously, to show your user the price, you could use displayPrice. This field contained currency and price. There was a price field as well the price without the currency or locale.

But what about the cases when you’d like to show your user how much he might save if he purchases the annual subscription instead of the monthly one? (And let’s be honest, this is a quite popular mechanic.) What if you also want to show how much he should pay for the annual subscription monthly?

In this case, you can use priceLocale to help you add information about the price and currency. The previous version of StoreKit had this functionality, but it was quite unstable – you just needed to fill the SKProduct field. But with the new API you can use just priceLocale and show the price wherever you want.

Server Environment Property

Environment – server environment in which the transaction was processed. This is an extremely useful property that can be used for testing and analytics purposes. For instance, you could use it to distinguish production purchases from the sandbox purchases so you don’t consider the testing data in your analytics. Previously, this information was available in the receipt and reflected the entire receipt, which was super inconvenient.

Recent Subscription Start Date

RecentSubscriptionStartDate represents the most recent period of continuous subscription period (subscription with no more than a 60-day gap between any two subscribed periods). In other words, it represents the earliest start date of a subscription in a series of auto-renewable subscription purchases that ignores all lapses of paid service shorter than 60 days.

For instance, if a user purchased the monthly renewable subscription on 8th of June 2021, and then renewed it once in a year (8th of June 2022), and between these periods he didn’t use this app or subscription, this field will contain the first date: 8th of June.

This is important information to determine the customer cohort that continuously uses your app. By knowing the information about this cohort, you can reward your loyal customers with bonuses and discounts. The information about unsubscribers will help you to take actions to win back lapsed customers.

Sentinel values

All the new properties that we’ve described above will be available starting iOS15. It will be available if you build your app with Xcode14 (which is available in beta). And all the properties will be available in Production and Sandbox environments.

What does sentinel values mean?

If you are testing StoreKit with Xcode and refer to new fields/properties, you’ll receive placeholders values. These are fields with a zero values.

This is a great screenshot that’ll help you to remember this information.

Btw, you can solve this problem super easily: just update your testing divide to iOS 16.

One more great screenshot that’ll help you to identify these placeholders.

All these new properties are available with App Store Server API and App Store Sever Notifications as well.

SwiftUI + StoreKit updates

Offer Codes Redeem Modifier in SwiftUI

Offer codes help you to acquire new customers and reward existing ones with discounts, free access, and more. With App Store Connect you can create unique custom codes. You can set a maximum redemption limit and choose whether or not to set an expiration date.

The update is quite simple: offer code redemption sheet has its own view modifier in SwiftUI, so you can easily process redemption flow with just a few lines of code and a binding boolean value. Available with iOS 16. This is the same functionality that was available in StoreKit and UIKit, but now is available in SwiftUI as well.

Updated possibility to request an app review

The second Swift UI Update is the possibility to request an app review. This also was available in UIKit, but from now on available for SwiftUI as well.

The limitations and best practices are the same:

You can show it max 3 times within a 365 days
You can’t ask people to review the same app version several times
You shouldn’t interrupt user flow
You shouldn’t request a necessary review as a result of a user action (completing the game level or achieving the results within the app). The user should have an option to skip this step. The code example:

New API for StoreKit Messages

Apple released quite an interesting mechanism to display the messages that are related to StoreKit. The simplest example: you increased the price for the purchase and you’d like to show the price increase consent alert to your users.

So, let’s take a closer look at this flow.

Your app goes to the foreground. StoreKit checks: are there some changes with the App Store? The App Store returns the message info to StoreKit, and StoreKit asks the listener for permission to display the message or defer it (if you’d like to create your own scenarios for these messages to appear).

But if StoreKit doesn’t include any listener, it will display the message over your app.

Our advice here is to add listener to not interrupt your user’s flow and to not affect user experience, so the user won’t receive automate screen messages during the meditation app experience. You can ensure customers have a great experience by making sure that messages don’t appear at unexpected times.

The realisation is not that difficult. As Apple highlights, there will be official documentation on how to implement this functionality soon.

Application username

This is a field in which you can add the unique ID of the users from your system just to connect your user with their purchases. Those familiar with StoreKit can tell that this field was available earlier: so what’s the update?

Well.. you’re right, this field already exists and its title is applicationUsername. It was receiving any string value, but the official documentation recommended sending UUID into this field.

The update is that StoreKit2 includes the new additional field appAccountToken. The main difference is that this field is geared to receive UUID format only, not any random string value. The great thing is that all UUID strings from the previous StoreKit will be available in the new version of StoreKit as a part of appAccountToken.

With StoreKit2 this value will appear in appAccountToken. It is a kind of backward compatibility (in case you use UUID in applicationUsername). The needed value will appear in StoreKit Transaction, App Store API, and App Store Server Notifications.

Conclusion

In this article, we briefly discussed what was presented for in-app purchases during WWDC22, hope it was useful!

If you'd like to learn more on how to handle StoreKit errors, please follow our guide. Also, recently I've created an article on how to solve SKErrorDomain 0, feel free to check!

DEV Community: Surik Sarkisyan

What does restore purchase mean?

What does restore purchase mean?

Cases for restoring purchase

What products could be restored?

How to configure restore purchases on iOS?

How to configure restore purchases on Android?

Conclusion

How to send in-app subscription events to Firebase, Google Analytics, and Google Ads

Google Analytics for Firebase SDK

Firebase Integration: How to send subscription events to Firebase and Google Analytics

How to link Firebase Google Analytics to Google Ads

What Google App Campaigns are

How to optimize Google Ad based on Firebase conversion events data

Google App Campaigns optimization by conversion event

Google App Campaigns optimization by the audience

Conclusion

SKErrorDomain Code=0. What is it and how to fix it?

SKErrorDomain Code=0 in the sandbox environment

SKErrorDomain Code=0 during the review process

SKErrorDomain Code=0 in production environment

Submit a bug report about SKErrorDomain Code=0

What’s new in StoreKit testing (WWDC22 updates)

StoreKit updates in Xcode 14

Advanced subscription cases

Refund requests

Offer codes

Price increases

Billing retry and grace period

Sandbox updates

Sandbox Apple ID creation

App Store Connect API

Billing failure simulation

Conclusion

WWDC22 overview: how to integrate and migrate in-app purchases to App Store Server API

Using the App Store Server API

Which endpoints are available with the new API?

How to get originalTransactionIds with the Original StoreKit?

How to get originalTransactionIds with the StoreKit 2?

How to handle originalTransactionIds with both versions of StoreKit?

Signing JSON Web Tokens

How to construct JSON Web Token for your app?

Header

Payload

Verifying signed transactions

Migration from verifyReceipt to App Store Server API

How to check the subscription status of the particular user

How to receive the latest transactions of the user

Conclusion

What’s new with in-app purchases: WWDC 2022 overview

New App Transaction API is released

How to handle switching business models with the new App Transaction API

New Properties in StoreKit

PriceLocale

Server Environment Property

Recent Subscription Start Date

Sentinel values

SwiftUI + StoreKit updates

Offer Codes Redeem Modifier in SwiftUI

Updated possibility to request an app review

New API for StoreKit Messages

Application username

Conclusion

How to get `originalTransactionIds` with the Original StoreKit?

How to get `originalTransactionIds` with the StoreKit 2?

How to handle `originalTransactionIds` with both versions of StoreKit?