Integrating SiriKit Payment Intents into your App
Intro
I always thought making an iOS app interact with a virtual assistant such as Siri would be an uphill struggle. I was surprised to learn it is actually quite an easy task. Ever since iOS 12, SiriKit has been evolving in order to provide users cool new ways of interacting with their apps without even needing to open the phone. Enabling developers to potentialize functionalities with voice recognition and pre-set commands, increasing our app frequency of use and encouraging user retention.
SiriKit offers a variety of categories of recognizable commands, such as; sending messages, handling lists, notes, performing payments, booking a reservation and way more. These are called SiriKit Domains.
In this post, we are going to focus on payment intents and how to integrate them into your app. After reading this tutorial we are going to be familiarized with:
- INSendPaymentIntent
- INRequestPaymentIntent
Let's get started
In order to support Siri interactions, we need to configure our project, here is what we will go through:
1-. Enable Siri extension
2-. Add required frameworks
3-. Set Info.plist actions
4-. Add extension target
5-. Set Siri target capabilities
1-. Enable Siri extension
On your Xcode project select the main target and go to Signing & Capabilities. Then, click on the + icon to add the Siri capability. Note: A paid developer account is required in order to access this capability. Otherwise you won't see it listed.
2-. Add required frameworks
Go to the General tab and click on the + icon under Linked Frameworks and Libraries list. Add Intents.frameworks
3-. Set Info.plist actions
Under your Custom iOS Target Properties, add Privacy — Siri Usage Description
with a value that explains the Siri integration purpose.
4-. Add extension target
Because intents are handled outside of the main app target, we need to create a new Intents Extension target. Go to File > New > Target and select Intent Extension. Allow it to be added to the scheme.
5-. Set Siri target capabilities
Once the Siri target is created correctly, you need to add both INRequestPaymentIntent
and INSendPaymentIntent
to its brand new Info.plist.
It’s all set! Now we are ready to start implementing our payment extensions. YAY!
Intents Extension
The out of the box intent extension target that we just created comes with a single class called IntentHandler
. Because each of our intents requires its own specific handler, we are going to extend the IntentHandler as INSendPaymentIntentHandling
and INRequestPaymentIntentHandling
.
Intents lifecycle consists of three phases: resolve, confirm and handle.
Resolve
During the resolution phase, we need to validate the individual parameters of our intents and ask SiriKit for clarifications as needed. When dealing with payments there are five main parameters we might be interested in resolving before handling the intent: payee, payer, note, currency, amount.
Do we want the user to always include a note when sending or requesting a payment? Is currency limited to USD? This is the stage when Siri is meant to help you define your required parameters.
Confirm
The purpose of the confirmation phase is to perform one final check of all intent parameters and verify that we are ready to fulfill the intent before sending.
Handle
The final step. If you validate the intent successfully, SiriKit asks you to handle the intent and perform the expected action. This is the place to call your service, update database, or whatever you need to do. When you are done, report back to Siri how everything went.
And that's it!
Now you should be able to run your app and tell Siri “Send $10 to <Your contact name>”
Note: Siri payment intent are only available when phone is unlocked
Handling Errors
SiriKit provides response codes to inform Siri how the intent handling went. This is your way of communicating to the user any details before proceeding or to indicate if something goes wrong along the way. Here is a list of some of codes that might be useful when integrating Siri with your app functionality.
INRequestPaymentIntentResponse/ INSendPaymentIntentResponse
failurePaymentsAmountAboveMaximum
: The request failed because the specified amount was above the allowed maximum established by your app.failurePaymentsAmountBelowMinimum
: The request failed because the specified amount was below the required minimum established by your app.failureCredentialsUnverified
: The request failed because you couldn’t verify one of the user’s credentials.failureNotEligible
: The request failed because a user was not eligible to perform the transaction.failureInsufficientFunds
: The request failed because user does not have sufficient funds in their account to cover the transaction.
INRequestPaymentPayerResolutionResult/INSendPaymentPayeeResolutionResult
noValidHandle
: The unique handle that you use to identify the payer is invalid or missing.noAccount
: The payer does not have an account in your app.
Source code is available here: https://gist.github.com/isisnaomi/3b4c927790dd4e88116d813a1a12bd5f