Version: 4.4.0

Resources

Our sample app using the PingOne Fraud for Web SDK.

Getting Started

To integrate the PingOne Fraud for Web SDK on your client:

Import the Fraud SDK script. Include the following script section in each relevant page of your app:

<script id="stPingId"
         src="https://assets.pingone.com/p1f/web-sdk/${LATEST_VERSION}/p1f-sdk.js?appId=<appId>"
         defer>
 </script>

The id="stPingId" setting is mandatory.

Initialize the SDK by adding a listener to the SecuredTouchReadyEvent event:

function onSecuredTouchReady(callback) {
     if (window['_securedTouchReady']) {
         callback();
     } else {
         document.addEventListener('SecuredTouchReadyEvent', callback);
     }
 }
 onSecuredTouchReady(function () {
     _securedTouch.init({
         url : "https://<securedtouch-backend-host>",
         appId: "<appId>",
         appSecret: "<appSecret>",
         userId: "<currentUserId>",
         sessionId: "<sessionId>",
         isDebugMode: false,
         isSingleDomain: false,
     }).then(function () {
         console.log("SecuredTouchSDK initialized successfully");
     }).catch(function (e) {
         console.error("An error occurred. Please check your init configuration", e);
     });
 });

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`.

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.

Note: You need to pass this token each time you call the Fraud Evaluations API, even though the clientToken property for the Fraud Evaluations API is indicated as optional, and whether or not your use case includes bot detection.

To get the token from the Fraud SDK, add a call to:
```
window['_securedTouchToken']
```
An event is fired every time the token changes. For example:
```
document.addEventListener('SecuredTouchTokenReadyEvent', function () {
   // token = window['_securedTouchToken'];
 });
```
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>, <session-id>)
```
- If the application loses the unique identifier of the user (for example, after sign off), add a call to:
```
_securedTouch.logout()
```
- On sign off, the Fraud SDK clears the session ID by default. 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>)
```
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 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 username:
```
<input id="username">
```
Add tags. You can tag specific points in time during a session that will be saved by the Fraud service. Tags can be added remotely by the PingOne Fraud platform (using CSS selectors), or programmatically using JavaScript or HTML attributes.
- To add a tag using HTML, add the data-st-tag attribute to an element with the tag key. The tag will be added when the element is clicked. You can also add additional information, by adding the data-st-tag-value attribute. For example:
```
<button type="button"
          data-st-tag="placeOrderClick"
          data-st-tag-value="{{payment_type}}">Place Order</button>
<button type="button"
data-st-tag=“cancelClick”>Cancel</button>
```
- To add a single tag, use:
```
_securedTouch.addTag(<tag-name>)
```
- To add a tag with additional information, use:
```
_securedTouch.addTag(<tag-name>, <tag-value>)
```
- To add multiple tags:
```
_securedTouch.addTag(<tag-name>, <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()
```

Useful operations

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.

Collecting mouse and gestures data:

Mouse (desktop) and touchscreen gestures (mobile devices) are collected by default for the entire DOM (Document Object Model).

Context APIs

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

Collect user information

When collecting user information, add data-st-field entries for username and password:

<input type="email" id="username" placeholder="..." data-st-field="username"/>
<input type="password" id="password" data-st-field="password"/>

For the “input type=” entries, use the input type used for the user ID.

Login page

On every sign-on attempt, call the loginAttempt method with the login type. For example:

// For email login. This doesn't collect the email address itself, only anonymized features (such as, length, and email domain).
  _securedTouch.LOGIN.loginAttemptEmail("email@example.com");
// For phone number login (countryCode, nationalNumber):
_securedTouch.LOGIN.loginAttemptPhoneNumber(“1”, “2025550134”);
// For social login
_securedTouch.LOGIN.loginAttempt(_securedTouch.SocialType.GOOGLE);

The SocialType value can be: FACEBOOK, GOOGLE, APPLE, TWITTER, LINKEDIN, or a custom string. For example: _securedTouch.LOGIN.loginAttempt("PROVIDER_NAME");.

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.LOGIN.accountCreationTime(EPOCH_TIME_IN_SECONDS);.
On failed sign-on attempt, call the loginFailed method. For example: _securedTouch.LOGIN.loginFailed();.
When the user starts a forgot password flow, call the forgotPassword method.

Registration page

On every registration attempt, call the registrationAttempt method with the registration type. For example:

// for email registration
  _securedTouch.REGISTRATION.registrationAttemptEmail("email@example.com");
// For phone number registration (countryCode, nationalNumber):
_securedTouch.REGISTRATION.registrationAttemptPhoneNumber(“1”, “2025550134”);
// for social registration
_securedTouch.REGISTRATION.registrationAttempt(_securedTouch.SocialType.GOOGLE);

The _securedTouch.SocialType value can be: FACEBOOK, GOOGLE, APPLE, TWITTER, LINKEDIN, or a custom string. For example: _securedTouch.LOGIN.loginAttempt("PROVIDER_NAME");.

On a successful registration, call the registrationSuccess method. For example: _securedTouch.REGISTRATION.registrationSuccess();.
On a failed registration, call the registrationFailed method. For example: _securedTouch.REGISTRATION.registrationFailed();.
When a referral was applied on a certain registration, call the referralApply method.

Account page

On every shipping address change, call the shippingAddressChanged method with the new shipping address. For example: _securedTouch.ACCOUNT.shippingAddressChanged("new address");.
On every account’s email change, call the emailAddressChanged method with the new email address. For example: _securedTouch.ACCOUNT.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.ACCOUNT.notificationChanged(true, "promotions");
// the user turned off new coupons notifications
_securedTouch.ACCOUNT.notificationChanged(false, “coupons”);

On a language settings change, call the languageChanged method with the new language. For example: _securedTouch.ACCOUNT.languageChanged("spanish");.
On a country settings change, call the countryChanged method with the new country. For example: _securedTouch.ACCOUNT.countryChanged("US");.
On a password settings change, call the passwordChanged method. For example: _securedTouch.ACCOUNT.passwordChanged();.
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.

Checkout page

On every purchase attempt, call purchaseAttempt with the payment method. For example: _securedTouch.CHECKOUT.purchaseAttempt(_securedTouch.PaymentMethod.CREDIT_CARD);. The available PaymentMethod values can be: PAYPAL, CREDIT_CARD, or a custom payment method. For example: _securedTouch.CHECKOUT.purchaseAttempt("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.CHECKOUT.purchaseSuccess();.
On a failed purchase, call the purchaseFailed method. For example: _securedTouch.CHECKOUT.purchaseFailed();.
On coupon usage, call the applyCoupon method. For example: _securedTouch.CHECKOUT.applyCoupon();.

Product page

When a user adds an item to the cart, call the addToCart method. For example: _securedTouch.PRODUCT.addToCart();.
When a user saves an item for later, or adds an item to their wishlist, call the saveItem method. For example: _securedTouch.PRODUCT.saveItem();.

Catalog page

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.

Challenge page

When the application challenges the user, call the challengeInvoked method with the challenge type. Some examples: _securedTouch.CHALLENGE.challengeInvoked("security questions"); or _securedTouch.CHALLENGE.challengeInvoked(_securedTouch.ChallengeType.HIDE_BILLING);. The available ChallengeType values are: RECAPTCHA, HIDE_BILLING.
If the user successfully completes the challenge, call the challengeSuccess method. For example: _securedTouch.CHALLENGE.challengeSuccess();.
If the user didn’t pass the challenge, call the challengeFailed method. For example: _securedTouch.CHALLENGE.challengeFailed();.

Cart page

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.

Orders page

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.

Chat page

When the user adds a message in the chat, call the addMessage method.

Feed page

When the user starts a stream, call the startStream method.
When the user ends a stream, call the endStream method.

Feedback page

When the user reports a fraud, call the reportFraud method.

Typescript definition

For the typescript definition, see the securedTouch.d.ts file in the SDK package.