Developer’s Guide to Family Sharing In-App Purchases
How to support and test Family Sharing in your apps
May 4, 2021
May 4, 2021
What is Family Sharing?
Family Sharing is a feature in Apple platforms that allows users to share digital purchases with members of their family — purchases like movies, books, TV shows, and even apps.
It’s been around for a few years now, but until recently app sharing was limited to purchases of entire apps, not in-app purchases.
So if an app was free to download but offered a subscription as an in-app purchase, the subscription wouldn’t be shareable, even if the Family Sharing badge was displayed on the App Store page. Users who purchased a subscription might feel deceived and blame the app developers.
This changed in December 2020. Now, Apple allows users to share in-app purchases, including subscriptions, with family members. Since then, many apps have started using Family Sharing for subscriptions.
In this post, we’ll talk about how Family Sharing works, how to support and test it, and a few of the benefits and drawbacks of enabling Family Sharing for your app.
How Family Sharing works
Users can set up an iCloud Family account to share in-app purchases with up to 6 people.
The “Share with Family” option can be found in the Settings app on iOS or macOS, or on icloud.com. Users can choose to share all of their shareable subscriptions with their family, or select specific individual subscriptions to share.
A note about compatibility:
Only non-consumables and subscriptions can be shared. Which makes sense — you don’t want a customer who bought a consumable for 50 coins to effectively get 300 coins if they share that purchase with their family.
Shared purchases work on older iOS and macOS versions. However, only more recent versions of macOS and iOS have a UI that supports managing shared subscriptions — tvOS and watchOS don’t have this yet.
Enabling Family Sharing for your app
It’s pretty easy to start supporting Family Sharing for in-app purchases. Simply go into App Store Connect, find the product you’d like to make Family Shareable (or create one), and turn on Family Sharing. It’s enabled on a per-product basis.
Note: Once Family Sharing is enabled for a given product, it can’t be disabled. This is so that if a user purchases a subscription for their entire family, the subscription won’t suddenly stop working for their family members and effectively be less valuable to them than when they purchased it.
Once Family Sharing is enabled, existing subscribers who have a family set up in iCloud will get a notification letting them know that they can now share the subscription with their family members.
Note: You should make sure that your paywall clearly states that a subscription can be shared with family members, since this might be very valuable to users. You can use the new property isFamilyShareable in SKProduct to selectively display an extra callout and explain the benefits of sharing the subscription.
Setting up support for Family Sharing with in-app purchases
Enabling Family Sharing in App Store Connect seems easy enough, but how about actually supporting it?
The good news is, you don’t have to do anything special to support Family Sharing for in-app purchases! 🎉
Apple designed Family Sharing for in-app purchases in such a way that most apps can support a bare-minimum implementation without having to touch any code. However, if you want to cover all use cases and provide the best possible experience for your users, you’ll have to make a few updates.
A couple of things to consider:
How to grant your users access to the content and revoke access when necessary
How you’ll calculate revenue
Granting and revoking access
When a user starts sharing a purchase (either because they just enabled Family Sharing for an existing purchase or because they just bought a shareable product), a purchase will be added to the transaction queue for each of their family members.
In order to provide the content to your users, you should make sure to observe the transaction queue as early as possible within your app flow. Once the transaction comes in, validate it with the /verifyReceipt endpoint and enable the content for the users.
Apple introduced a new API to the SKPaymentTransactionObserver for Family Sharing called paymentQueue(_:didRevokeEntitlementsForProductIdentifiers:).
This method is called when a shared purchase is no longer available to the user (for example, if a user leaves the iCloud family to start their own, or sharing is disabled for a purchase).
When this method is called, you should revoke access to the purchase for the current user. The purchase will also show up as expired in /verifyReceipt(see our post on how to read the receipts), so if a user doesn’t open the app, you can still revoke access when refreshing receipts.
When a user purchases a new subscription with Family Sharing enabled, it won’t show up on their family members’ devices right away. It takes about 60 minutes from when the purchase is made for the subscription to become available to other family members. This is intentional — it's meant to give the purchaser time to decide whether they actually want to share the subscription (e.g., if they subscribe to an app that contains content they might not want to share with their kids).
However, this delay only happens for new purchases, not renewals. If a user has already purchased a subscription and later turns on Family Sharing, there won't be a delay. The assumption is that at this point the user has made it clear that they really intend to share access.
If you’re calculating your app’s revenue from in-app purchases, you’ll need to make sure that you’re only counting family-shared transactions from the user who made the purchase, not their family members. Otherwise you might end up with a revenue number many times higher than what you actually made from that purchase.
When a user buys a Family Shareable in-app purchase, it will show up on their receipt as usual. However, the receipt will now include a new field called in_app_ownership_type with the value PURCHASED.
A new transaction will also be added to the queue for all their family members. The transaction will have a new web_order_line_item_id and original_transaction_id, as well as in_app_ownership_type with the value FAMILY_SHARED.
In order to accurately calculate revenue, make sure you only count transactions with in_app_ownership_type = PURCHASED.
Note: You don’t need to re-create the user’s family structure on your backend. In fact, this is difficult to do by design (to protect user privacy), and re-creating the user’s family structure doesn’t provide any benefit.
If you’ve followed along so far, your app should now be set up to grant Family Sharing access and track analytics. But there’s one more use case that you should consider in order to provide the best experience for your users.
When a user makes a purchase in your app, they usually go through a paywall that details all of the benefits that they’ll get by making the purchase. Some apps even show a tutorial for how to take advantage of the newly-unlocked content.
But family members that are granted shared access to an app never see the paywall, so they may not understand the value of the product. For example, let’s say you’re selling a Pro subscription, which unlocks access to specific features in your app. A family member may open up the app with Pro access already unlocked and never know what exclusive features they have access to.
Fortunately, there’s a way to educate users about the benefits of a purchase that has been shared with them. Use the in_app_ownership_type field from /verifyReceipt to let them know that a family member shared Pro access with them and what features they’ll get out of it.
If you’re using Introductory Pricing, when you calculate eligibility for users, you’ll need to make sure that you’re accounting for shared purchases as well. Luckily this part should be easy: just make sure that FAMILY_SHARED transactions aren’t filtered out when computing eligibility — if a family member has already taken advantage of intro pricing and shared it with their family, their family members shouldn’t be eligible for that intro pricing in the future.
Testing shared subscriptions
Sadly, Family Sharing doesn’t work in the Sandbox environment. So there’s no real way to test it, other than trying it out in Production.
The closest you can get is to fake a similar-looking scenario so you get a new transaction to show up in the payment queue. For example:
Purchase a subscription.
Let it expire naturally.
Go to Settings > App Store > Sandbox Account > Manage Subscriptions > and subscribe again.
This will generate a new transaction that shows up in the queue as soon as you re-open the app (which is similar to what happens when a family member shares a subscription with you). This flow will only help you test that you’re correctly subscribing to the queue and won’t miss events, but the receipts here won’t have the in_app_ownership_type set to FAMILY_SHARED.
Unfortunately, there’s no way to test the scenario where a user’s subscription is revoked. Just make sure that you’re subscribing to the payment queue and that paymentQueue(_:didRevokeEntitlementsForProductIdentifiers:) is implemented correctly.
Enabling Family Sharing with RevenueCat
Of course, you can always take the easy route and let us do the work for you!
If you’re already a RevenueCat customer, Family Sharing is automatically supported for your in-app purchases. Once you set them up in App Store Connect, Analytics and Entitlements will automatically work as expected.
All you need to do is:
Initialize the SDK as early as possible in your app flow so that transactions in the queue are detected right away.
In purchases-ios >= 3.11.0, use the new ownership_type field in EntitlementInfo to determine whether an Entitlement was granted to a user through a direct purchase or Family Sharing, and then educate users on the benefits of the in-app purchase.
Use SKProduct’s isFamilyShareable to selectively display a callout on your paywall notifying users that a given subscription can be shared with their family members. This is available through the Package in each Offering.
To check eligibility for introductory prices, use our API just like you normally would.