Online Enhanced Presentment Developer Integration Instructions - ads-ep/EpJs GitHub Wiki

This guide is a generic overview of the installation instructions for the Enhanced Presentment feature set. You will be provided with more detailed instructions and unique code snippets for your website.

To set up the JavaScript Library on your site, copy and paste the JavaScript configuration snippet shown below just before the closing </body> tag of your site’s templates.

<script>
/*
* Create placeholder methods so library
* can be called before it is finished loading
*/

  window.EpJs=window.EpJs||{snippetVersion:"1.0.2"},EpJs.init||(EpJs.on=function(){var s=["on"].concat(Array.prototype.slice.call(arguments));(EpJs.q=EpJs.q||[]).push(s)},EpJs.submitRTPS=function(){var s=["submitRTPS"].concat(Array.prototype.slice.call(arguments));(EpJs.q=EpJs.q||[]).push(s)},EpJs.generatePlacements=function(){});

  EpJsConfig = {
    env: 'STAGE', // STAGE | PROD defaults to PROD
  }
</script>

<script
  data-ep-js-key="XXXX-XXXX-XXXX-XXXX"
  async
  src="https://brand-sdk.kmsmep.com/bundle.js">
</script>

You will need to replace "XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX" in the data-ep-js-key field with your key, provided to you by your account manager.

The JavaScript configuration snippet should appear on every page of your site that will use the JavaScript Library, or in other words, everywhere a placement is added.

By default EpJs will direct all API calls to Production. In order to make requests to our staging environment, you must set the env EpJs config variable. Place the following snippet anywhere before the EpJs Library is loaded to set that value (full example above):

    <script>
      EpJsConfig = {
        env: 'STAGE', // STAGE | PROD
      }
    </script>

If the above env value is not set, requests will be made to production by default. Behind the scene, this env config value will set the prescreen API URL to our predefined staging endpoint. It will also send this value with all placement requests, so each placement in staging will use the corresponding environment for instant credit applications. This works similarly to how a different message may be rendered if a user is logged in or if an item is above a given price range.

Now that you have the JavaScript Library set up on your site, you’ll need to add in the placements. Your account manager will provide you with the actual Placement code snippets that you should add to your site for each placement. Note that your account manager may recommend you populate some of the null values.

Once the placements are set up on your site, they will display messaging served by the JavaScript Library. Clicking on a placement will launch an overlay window that displays the details of your credit card program and includes a button that links the customer to your application page.

The placements will inherit styles from your theme by default. If you'd like to further customize each placement to match your brand, follow the styling instructions at the bottom of this page.

Your account manager will provide you with specific instructions and placement ID to use, but the snippet below can be referenced as a general example.

<div data-ep-placement="49989304-445d-4002-95db-f94z99885447"
       data-amount-type="product"
       data-amount="65703"
       data-location="product"
       data-product-category="shoes"
       data-brand="nike"
       data-sku="NIKE-PEG-BL-43">
       </div>

If you need help customizing styles, please reach out to the EP team for guidance.

This section is relevant if you’ll be supporting the Apply & Buy capability. Through this method, you will receive the application decision. If approved, you’ll receive the Call ID that you can use at checkout to enable your customer to buy immediately after approval.

// Emitted after an application has been processed.
EpJs.on('FMC:RECEIVE_APPLICATION_RESULT', function(applicationResult){
  // Handle Application Result
  switch(applicationResult.result){
    case 'APPROVED':
      // Handle approved case
      break;

    case 'PENDING':
      // Handle pending case
      break;

    case 'ACCOUNT_EXISTS':
      // Handle account exists case
      break;

    case 'DECLINED':
      // Handle declined case
      break;

    case 'ERROR':
      // Handle error case
      break;
  }

});

// Emitted each time a customer submits an application.
// Available for analytics purposes
EpJs.on('FMC:SUBMIT_APPLICATION', function(){
  // Handle Application Submitted
});

interface ApplicationResult{
   result: 'APPROVED' | 'PENDING' | 'ACCOUNT_EXISTS' | 'DECLINED' | 'ERROR',
   callId?: string,
   decisionFull?: string
   error?: string;
}

// Approved Application Result
approvedApplicationResult = {
   result: 'APPROVED',
   callId: '16e64cfe-53fa-11ea-8d77-2e728ce88125',
   decisionFull: 'Application successfully approved'
}

// Pending Application Result
pendingApplicationResult = {
   result: 'PENDING',
   decisionFull: 'Application is pending'
}

// Account Exists Application Result
accountExistsApplicationResult = {
   result: 'ACCOUNT_EXISTS',
   callId: '16e64cfe-53fa-11ea-8d77-2e728ce88125',
   decisionFull: 'Account already exists'
}

// Declined Application Result
declinedApplicationResult = {
   result: 'DECLINED',
   decisionFull: 'Application declined'
}

// Application Error Result
applicationErrorResult = {
   result: 'ERROR',
   error: 'The user session timed out'
}

This section is relevant if you’re pre-screening through EP.

Use the submitRTPS method from EpJs to submit a customer's information to the pre screen api. If approved, an overlay with their pre approval offer will automatically be displayed to the customer. If the customer is not approved or if they already have an account, the request will complete in the background, and the customer will not see an overlay.

Create the customer info object

const primaryApplicant: RTPSPrimaryApplicant = {
  name: {
    firstName: 'Warren',
    lastName: 'Buffet'
  },
  address:{
    address1: '3555 Farnam St.',
    city: 'Omaha',
    state: 'NE',
    zipCode: '68131',
    country: 'USA'
  },
  location: 'cart',

  // Optional fields
  emailAddress: '[email protected]',
  mobilePhone: '8005552756',
  cartAmount: '89000', // Amount in cents
}

Start a Real Time Pre Screen Request. The results of this flow will be communicated through the event handler. Refer to the event documentation for a list of all of the supported event types.

EpJs.submitRtps(primaryApplicant);

Providing an optional FetchRtpsMockOptions argument will allow you to test the various Real Time Prescreen flows.

E.g.

type FetchRtpsMockOptions =
| 'success'
| 'noHit'
| 'makeOffer'
| 'ackknowledge'
| 'existingAccount'
| 'existingOffer'
| 'newOffer'
| 'error';

const mockOption: FetchRtpsMockOptions = 'success';

EpJs.submitRTPS(primaryApplicant, mockOption);

export interface RTPSPrimaryApplicant {
  name: RTPSName;
  address: RTPSAddress;
  location: 'homepage' | 'landing' | 'search' | 'product' | 'category' | 'banner' | 'checkout' | 'cart' | 'native-web' | 'navigation' | 'footer';

  emailAddress?: string;
  mobilePhone?: string; // Ex. 3015555555
  alternativePhone?: string;
  brandDefaultStoreNumber?: string;
  customerNumber?: string;
  loyaltyNumber?: string;
  cartAmount?: string;
  checkoutAmount?: string;
  consumerInsights?: {[key: string]: string}
  productAmount?: string;
  sku?: string;
  correlationData?: string;
  prescreenId?: string;
  customerAcceptedOffer?: boolean;
}

export interface RTPSName{
  firstName: string;
  lastName: string;
  middleInitial?: string;
}

export interface RTPSAddress{
  address1: string;
  address2?: string;
  city: string;
  state: string;
  zipCode: string;
  country: string;
}

export type FetchRtpsMockOptions =
| 'success'
| 'noHit'
| 'makeOffer'
| 'ackknowledge'
| 'existingAccount'
| 'existingOffer'
| 'newOffer'
| 'error';

This section is relevant if you’re using batch prescreen through EP. Batch prescreen is triggered from the same method as real time prescreen. EpJs.submitRTPS() Whether the customer enters the batch prescreen or realtime prescreen flow is determined by a combination of url query params, arguments pass into the method and validity of the prescreen ID.

Batch prescreen uses the same application decision events as real time prescreen and the Apply and Buy (Instant Credit) flow.

1. A batch prescreen acceptance URL needs to be determined by the Brand and configured with the batch system by ADS.

• This URL is where the customer will land after accepting their offer via email.
• This URL should also include information about the credit program in case the offer has expired.

2. When the predefined acceptance URL is loaded, the Brand should call EpJs.submitRTPS().

• The prescreen ID and attribution data will automatically be pulled from the URL.
• Any information passed into the method directly will override values pulled from the query params
• Passing in the customer info on file is optional. E.g. EpJs.submitRTPS(primaryApplicant) See RTPS Data Model
• If the prescreen ID is not present or is expired, the customer will be prompted to provide a prescreen ID through the modal.

Example of batch generated acceptance link that would be embedded in an email: https://{batch prescreen acceptance page}/?prescreenId={unique prescreen id}&loyaltyNumber={customer loyalty number}&channel=4&subChannel=B

With the ADS hosted solution, the customer is directed to an ADS hosted standalone acceptance page. After completion of the application, they are redirected to a predefined URL on the Brand's site with the callback ID included in the query params. Once this page is loaded, the Brand will exchange the callId on their backend for account number.

This is trigged with the same method and URL as Batch prescreen via email

Batch prescreen via printed mail typically takes advantage of a vanity URL and offer lookup service to reduce the overall length of the acceptance URL.