Integrating PKCE authentication & cross entitlement for Piano
This page outlines exactly what we need from you in order for us to set up Piano authentication & cross entitlement using PKCE in your apps.
If we are setting up a PKCE authentication flow for your app(s) we will need (ideally for Sandbox and Production):
- Your Piano Application ID (AID) - you'll find this on the home page of your Piano dashboard
- Your Piano API token - also on the home page of your Piano dashboard
- The resource ID(s) that should allow access to the app
- Piano White Labelling Domain (if configured). See Piano's docs here for more details.
- Test users
You will also need to add the callback URIs that need to be configured in Piano (this is also required for cross entitlement).
The callback URIs are usually of the form below and all platforms need to be added.
- iOS: bundle.id://authCallback (e.g. com.acme.app://authCallback)
- Android: package.id://authCallback (e.g. com.acme.app://authCallback)
- Web: https://webreader.vanity.root.url/ (e.g. https://reader.acme.com/)
If you do not know your bundle ID/package ID or vanity domain, please let us know
Watch out for non-matching domains
For clients that do not have a whitelabelled domain, you need to ensure that the correct version of the Piano domain is used. Some clients use id.tinypass.com while others use id.piano.io - if these don't match you'll see non-matching URI errors early in the slow.
Cross entitlement between Piano and the app stores
External API setup
You'll need to create External APIs for iTunes and Google Play receipt postback. Go to Piano > Manage > External APIs > New
External APIs are not always enabled by default. If you do not see them, contact Piano Support and request that your Piano instance is allowed External API configuration.
- Select Apple iTunes from the drop-down:
- set 'Title' to Apple App Store
- keep Enforce uniqueness set to ON
- set 'Password' to your Apple app store secret (see notes below)
To find your Apple app store secret, go to App Store Connect > Users and Access > Shared Secret:
Apple, Account Creation & Deletion
If you choose to include a link to create a new account, Apple requires that you provide a way for users to delete their account. This can be a link to a webpage.
- Select Google Play In-app Billing from the drop-down
- set 'Title' to Google Play Store
- select Google Play In-app Billing from the drop-down
- set 'Public Key' to the Public Key from the Google Play Console
- set 'Service account' to your service account key
- leave 'Description' blank.
To find your Public Key, go to Google Play Console > Monetisation setup > and scroll down to Licensing:
For the Service account, you'll need a Google service account that's been granted access to the Subscriptions API > https://docs.pugpig.com/360014073437-Google-Play-Universal-Receipt-Store-Auth
Linking terms to App Store product IDs
If you sell in-app subscriptions and wish to enable cross entitlement, we'll also need the Term IDs for the external terms set up in Piano (separate for iOS & for Google Play), along with which in-app purchase Product IDs they map to. For instance Term ID TM19OE92ABBZ = com.yourapp.sub.1month
To create a Piano term that links to an App Store product go to Piano > Manage > Terms > New and select EXTERNAL SERVICE. Once you've given the term a name and description and selected which resource the term should give access to click create, then you'll see the option to add the product ID of the associated App Store subscription in the field 'Product ID'.
The App Store Product IDs can be found in their respective app stores. For iOS, you can find the subscriptions SKUS in App Store Connect > In App Purchases > Subscription groups:
For Google Play these will be in Products > Subscriptions: