Version: 4.4.0
To integrate the PingOne Fraud for iOS SDK on your client:
Add the SDK to your app using CocoaPods. If you’re new to CocoaPods, see the official documentation at https://guides.cocoapods.org/using/using-cocoapods for information about creating and using Podfiles.
Open your project’s Podfile and add the following to your app’s target:
STVersion = 'VERSION_NUMBER'
pod ‘PingOneFraudSDK’, :podspec => “https://assets.pingone.com/p1f/ios-sdk/#{STVersion}/p1f-sdk.podspec”
Set the SDK version number. From the command line, install the PingOne Fraud pod library in your project:
pod install
Register PingOne Fraud.
a. Import the PingOne Fraud module:
import SecuredTouch
If you look in your AppDelegate.swift
file you’ll see that @UIApplicationMain
appears directly before class AppDelegate
. This is a special attribute that tells the Swift compiler to generate code to launch your application using default settings. You need to delete @UIApplicationMain
from that file, and instead create a new Swift file called main.swift
in your project, adding the following in this file:
import Foundation
import UIKit
import SecuredTouch
UIApplicationMain(
CommandLine.argc,
CommandLine.unsafeArgv,
NSStringFromClass(STApplication.self),
NSStringFromClass(AppDelegate.self)
)
Initialize the SDK. You’ll typically do this in your app’s application:didFinishLaunchingWithOptions:
method. For example:
let initParams = STInitParams(applicationId: "<appId>", andAppSecret: "<appSecret>", andServerHost: "<serverHost>")
initParams.userId = "<currentUserId>"
initParams.sessionId = "<sessionId>"
initParams.debugMode = false
let securedTouch = SecuredTouch.initSDK(initParams)
securedTouch?.onSecuredTouchInitialized { (uuid) in
print(“SecuredTouch Initialized (uuid!)”)
}
securedTouch?.onSecuredTouchError { (uuid, message, code) in
print(“SecuredTouch onError - uuid: (uuid!), message: (message ?? “”), code: (code)”)
}
Parameter | Description |
---|---|
appId |
The PingOne application ID. See the PingOne Fraud admin documentation for instructions on getting the PingOne Fraud SDK access credentials. |
appSecret |
The PingOne application secret. See the PingOne Fraud admin documentation for instructions on getting the PingOne Fraud SDK access credentials. |
serverHost |
The Fraud service host. See the PingOne Fraud admin documentation for instructions on getting this information. |
userId |
If the user is already identified (signed on) when initializing the Fraud SDK, their user ID should be set here. If the user ID originates from PingOne, use the user ID for the PingOne environment. For all other cases, use a non-personal user identifier. |
sessionId |
The user’s session ID. To query the Fraud service for the trust scores through the backend system, the Fraud service and the backend system must have a shared identifier for each session. The session ID usually serves as this shared identifier. |
consoleLogEnabled |
(Optional) Set this to true to enable console logging by the SDK. Defaults to false . |
externalLogsEnabled |
(Optional) Set this to false to prevent the SDK from sending error logs to an external logging service. Defaults to true . |
Set an event listener to get calls on successful SDK initialization, or for when something goes wrong in the SDK.
Parameter | Description |
---|---|
uuid |
Unique identifier for the entire lifetime of the SDK. This value stays the same as long as the app’s process is alive. Also available through securedTouch?.getInstanceUUID() . |
message |
The nature of the failure. |
code |
Internal error code. |
Fetch a Fraud token. The SDK generates a token that’s used for Fraud BOT detection capabilities. You’ll need to share the token with your application backend so a call with the fetched token can be sent from this backend to the Fraud Evaluation API to retrieve the risk assessment for a session.
To get the token from the Fraud SDK, add a call to:
securedTouch?.getToken()
An event is fired every time the token changes. For example:
securedTouch?.onTokenReady {
print("SecuredTouch Token is ready, \(securedTouch!.getToken()!)")
}
Don’t use your application to store the token, and instead share the token stored by the SDK.
User log in and log out. You can do this differently, depending on the following:
When the application receives the user ID, or any other unique identifier of the user (for example, after sign on), add the call:
securedTouch?.login(<user-id>)
If you have a session ID, you can use:
securedTouch?.login(<user-id>, andSessionId: <session-id>)
If the application loses the unique identifier of the user (for example, after sign off), add a call to:
securedTouch?.logout()
If you have a session ID after the user has signed off, use the following call instead of the call above:
securedTouch?.logout(<session-id>)
Add meaningful IDs to input fields and buttons. Meaningful IDs are required to ensure proper identification of the UI element for detection purposes. Here’s an example for a meaningful ID that can be added to a Login button:
Set the session ID. To query the Fraud service for the trust scores through the backend system, the Fraud service and the backend system must have a shared identifier for each session. The session ID usually serves as this shared identifier. To set the session ID after the application has it, call:
securedTouch?.setSessionId(<session-id>)
Add tags. You can tag specific points in time during a session that will be saved by the Fraud service.
Option | Command |
---|---|
Add a single tag | securedTouch?.addTag(<tag-name>) |
Add a tag with additional information | securedTouch?.addTag(<tag-name>, withValue: <tag-value>) |
Add multiple tags | securedTouch?.addTag(<tag-name>, withValue: <tag-value>).addTag(<tag-name>) |
Flush the buffer. Flushing the buffer forces the SDK to send buffered data to directly to the PingOne Fraud backend platform. Usually the built-in automatic flush should be sufficient, so this function should not be used unless instructed to do so by Ping Identity Professional Services.
securedTouch?.flush()
Pause or resume the PingOne Fraud SDK activity, networking, and data collection:
Option | Command | Description |
---|---|---|
Pause the SDK | securedTouch?.pause() |
Causes the current state and session ID to be saved, and used on resuming SDK operations. |
Resume the SDK | securedTouch?.resume() |
Resumes normal SDK operations. |
Pause or resume behavioral data collection:
Option | Command | Description |
---|---|---|
Pause behavioral data collection | securedTouch?.pauseBehavioralData() |
The SDK stops collecting events related to physical interaction (such as, touchscreen, device sensors, and keyboard). All other SDK activity continues as normal. |
Resume behavioral data collection | securedTouch?.resumeBehavioralData() |
Resumes SDK operations related to physical events. |
Get a unique identifier for the entire lifetime of the SDK: securedTouch?.getInstanceUUID()
.
PingOne Fraud does not collect email addresses or phone numbers, but their anonymized features instead (such as, email domain, length, phone number, and country code).
On every sign-on attempt, call the loginAttempt
method with the login type. For example:
// For email login.
securedTouch?.loginContext.loginAttemptEmail("email@example.com")
// For social login
securedTouch?.loginContext.loginAttempt(with: .google)
The social provider value can be: facebook
, google
, apple
, twitter
, linkedin
, or a custom string. For example: securedTouch?.loginContext.loginAttempt(with: "custom_provider")
.
On a successful sign-on attempt, call the accountCreationTime
method with the UNIX epoch timestamp (in seconds) of the account creation time. For example: securedTouch?.loginContext.accountCreationTime(EPOCH_TIME_IN_SECONDS)
.
On failed sign-on attempt, call the loginFailed
method. For example: securedTouch?.loginContext.loginFailed()
.
When the user starts a forgot password flow, call the forgotPassword
method.
On every registration attempt, call the registrationAttempt
method with the registration type. For example:
// for email registration
securedTouch?.registrationContext.registrationAttemptEmail("email@example.com")
// for social registration
securedTouch?.registrationContext.registrationAttempt(with .google)
The social provider value can be: facebook
, google
, apple
, twitter
, linkedin
, or a custom string. For example: securedTouch?.loginContext.loginAttempt(with: "custom_provider")
.
On a successful registration, call the registrationSuccess
method. For example: securedTouch?.registrationContext.registrationSuccess()
.
On a failed registration, call the registrationFailed method
. For example: securedTouch?.registrationContext.registrationFailed()
.
When a referral was applied on a certain registration, call the referralApply
method.
On every shipping address change, call the shippingAddressChanged
method with the new shipping address. For example: securedTouch?.accountContext.shippingAddressChanged("new address")
.
On every account’s email change, call the emailAddressChanged
method with the new email address. For example: securedTouch?.accountContext.emailAddressChanged("new_email@example.com")
On every notification settings change, call the notificationChanged
method with the updated notification state (on/off) and the notification information. For example:
// the user turned on promotion notifications
securedTouch?.accountContext.notificationChanged(true, withInfo: "promotions")
// the user turned off new coupons notifications
securedTouch?.accountContext.notificationChanged(false, withInfo: “coupons”)
When the user tries to delete an account, call the deleteAccount
method.
When the user tries to see payment methods available in the account, call the paymentMethodDisplay
method.
When the user clears account history, call the clearHistory
method.
When the user buys a gift card, shares a gift card, or redeems a gift card, call the useGiftCard
method.
On every purchase attempt, call purchaseAttempt
with the payment method. For example: securedTouch?.checkoutContext.purchaseAttempt(with: .credit_card)
. The available PaymentMethod values can be: paypal
, credit_card
, or a custom payment method. For example: securedTouch?.checkoutContext.purchaseAttempt(with: "other payment method")
. Only the payment method type is specified. Do not specify any payment identifiers (such as, credit card number).
On a successful purchase, call the purchaseSuccess
method. For example: securedTouch?.checkoutContext.purchaseSuccess()
.
On a failed purchase, call the purchaseFailed
method. For example: securedTouch?.checkoutContext.purchaseFailed()
.
When a user adds an item to the cart, call the addToCart
method. For example: securedTouch?.productContext.addToCart()
.
When a user saves an item for later, or adds an item to their wishlist, call the saveItem
method. For example: securedTouch?.productContext.saveItem()
.
When the user views catalog details, call the viewDetail
method.
When the user follows a channel, call the followChannel
method.
When the user unfollows a channel, call the unfollowChannel
method.
When the application challenges the user, call the challengeInvoked
method with the challenge type. Some examples: securedTouch?.challengeContext.challengeInvoked(with: "security questions")
or securedTouch?.challengeContext.challengeInvoked(with: .hide_billing)
. The available challenge type values are: recaptcha
, hide_billing
.
If the user successfully completes the challenge, call the challengeSuccess
method. For example: securedTouch?.challengeContext.challengeSuccess()
.
If the user didn’t pass the challenge, call the challengeFailed
method. For example: securedTouch?.challengeContext.challengeFailed()
.
When the user clears the cart, call the clearCart
method.
When the user deletes an item from the cart, call the deleteItem
method.
When the user goes to the checkout page, call the goToCheckout
method.
When the user opens a dispute, call the openDispute
method.
When the user views a dispute, call the viewDispute
method.
When the user views an order’s details, call the viewOrderDetails
method.
addMessage
method.When the user starts a stream, call the startStream
method.
When the user ends a stream, call the endStream
method.
reportFraud
method.