Integrating PKCE authentication & receipt postback for Piano

This page outlines exactly what we need from you in order for us to set up Piano authentication & receipt postback using PKCE in your apps.

See here for a general overview of web-based authentication integrations in Pugpig apps using PKCE. And see here for an introduction to in-app purchase and receipt postback.

Authentication

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
• The PKCE/OAuth client ID - to find this click 'Edit business' on the Piano home page, select 'User Provider', then click to edit the 'Piano ID' box. There will be an entry for OAuth client_id on the following page
• Test users

You will also need the callback URLs that need to be configured in your provider. The callback URLs are usually of the form below. If you do not know your bundle ID/package ID or vanity domain, please let us know:

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/)

Receipt postback -- Piano setup

Add the redirect URL to Piano

In Piano, go to Edit Business > User Provider > Piano ID > Edit > Then switch to the ‘Authorized’ tab.

You’ll add all of the above callback URLS (e.g., iOS: bundle.id://authCallback (e.g. com.acme.app://authCallback) to the list of REDIRECT URLS. 

External API setup

note: if you do not see External APIs in Piano, contact Piano Support and request that the Piano instance is allowed External API configuration

You'll need to create External APIs for iTunes and Google Play receipt postback. Go to Piano > Manage > External APIs > New

Configuring for iTunes:

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)
• set 'Receipt validation url' to https://buy.itunes.apple.com/verifyReceipt if production, https://sandbox.itunes.apple.com/verifyReceipt if configuring on Sandbox

To find your Apple app store secret, go to App Store Connect > Users and Access > Shared Secret: 

Configuring for Google Play:

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 Google Play Console (see notes below)
• set 'Service account' to the array value from Firebase (see notes below)
• leave 'Description' blank.

To find your Public Key, go to Google Play Console > Monetisation setup > and scroll down to Licensing:

For Google Play, you'll need a service account that's been granted access to the Subscriptions API > https://developers.google.com/android-publisher#subscriptions

Linking terms to App Store product IDs

If you sell in-app purchase subscriptions and wish to enable receipt postback, we need everything in the section above, plus the Term IDs for the external terms set up in Piano (there will be a separate one 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, 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: