Amex-perks-sdk NPM

Perks SDK

The SDK has been built to make it easy for merchants to integrate with the Amex Perks ecosystem. It provides several critical methods for validation and reporting, making integration seamless.

Integration steps

Add the library as a dependency to your project
Initialize SDK and invoke relevant functions
Done

Installation steps

To install using npm npm install --save amex-perks-sdk
To install using yarn yarn add amex-perks-sdk

Usage

Initializing the SDK

To use the SDK, the developer has to initialize the SDK first.

...
import { init } from 'amex-perks-sdk'
...
...
...
componentDidMount() {
  ...
  const config = { 
    mode: development, 
    campaignUuid: some-unique-id, 
    merchantApiKey: some-key 
  }
  ...
  init(config)
  ...
}

In case the SDK has not been initialized, the SDK will throw an error message “The SDK has not been initialized”.
The config is a javascript object which has the following
- mode type of String that can accept the following three variables to toggle between the SDK’s environments: development, qa & production.
- campaignUuid type of String that takes uuid of the campaign
- merchantApiKey type of String that takes the API key of the merchant
- shouldStripUrl type of Boolean that determines whether the query string parameters should be removed from the URL on validation, it defaults to true.
In case the campaign uuid needs to be switched before initialization The SDK has a function called, getCampaignUuid. This will return the campaign uuid from either the url (if the url is not stripped) or the local storage of the browser (if the url is stripped), and will allow you to toggle between campaign uuid for the co-branded page and the Marketplace.
```
...
import { getCampaignUuid, init, validateUser } from 'amex-perks-sdk'
...
...
...
componentDidMount() {
  const campaignUuid = getCampaignUuid()
  ...
  const config = { 
    mode: development, 
    campaignUuid: campaignUuid, 
    merchantApiKey: some-key,
    shouldStripUrl: false 
  }
   init(config)
   validateUser()
  ...
```

In case the URL should not be stripped

...
import { init } from 'amex-perks-sdk'
...
...
...
componentDidMount() {
  ...
  const config = { 
    mode: development, 
    campaignUuid: some-unique-id, 
    merchantApiKey: some-key,
    shouldStripUrl: false 
  }
   init(config)
   validateUser()
  ...

Validating a user

When the application is loaded for the first time

React

In the following example, we have invoked validate user in the componentDidMount of the application container. This ensures that whenever a user arrives on the website, the SDK will validate whether the user is an Amex Card Holder. If the user is invalid, the user will be redirected to the co-branded merchant url, or back to the Marketplace url depending on the user's entry point.

Using class components

...
import { validateUser } from 'amex-perks-sdk'
...

...
componentDidMount () {
    ...
    // validates the user
    // will redirect the user to the cobranded url if the user is invalid.
    validateUser()
    ...
}

Using hooks

...
import { validateUser } from 'amex-perks-sdk'
...

...
function App () {
    ...
    useEffect(() => {
    ...

    // validates the user
    // will redirect the user to the cobranded url if the user is invalid.
    validateUser()

    ...
    }, [])

    ...
}

On demand user validation

React

In the following example, we have invoked the validate user in the click handler of a button. The SDK supports lazy validation. This allows the merchant to postpone user validation from being triggered when the application is loaded to when the user is about to redeem the offer.

...
import { validateUser } from 'amex-perks-sdk'
...

...
async function handlePayment () {
    ...
    /**
    * validate the user. If the user is valid the control flow will
    * proceed ahead else the user is re-directed back to the co-branded page
    **/
    await validateUser()
    makePayment() // some method which, when invoked begins the payment process.
    ...
}

Redeeming an offer

React

Once the user completes checkout on the merchant website, the offerRedeemed method from the SDK must be invoked in order to report details about the redeemed offer to the Amex back-end.

...
import { offerRedeemed } from 'amex-perks-sdk'
...

    ...
    // in this example,
    // makePayment is assumed to be an async method responsible for payment.
    // Once the payment is done the handler passed to the `.then` will be executed
    // offerRedeemed accepts a paymentInfo variable which accepts,
    // order_cost, currency and some metadata
    makePayment().then(response => {
        ...
        offerRedeemed({
          "order_cost": 999,
          "currency": "USD",
          "metadata": {
              offer: '30% off on 3 months subscription'
          }
        })
        ...
    })
...

Scheduling an appointment

React

If the user wants to schedule an appointment on the merchant website, the scheduleAppointment method can be invoked in order to report details about the scheduled appointment, or inform that the user has just booked an appointment to the Amex back-end.

...
import { appointmentScheduled } from 'amex-perks-sdk'
...

    ...
    // in this example,
    // scheduleAppointment is assumed to be an async method
    // responsible for scheduling an appointment.
    // Once the appintment is scheduled the handler passed to `.then` will be executed
    // appointmentScheduled accepts an appointmentInfo variable which can have
    // params like appointment_date and appointment_with
    scheduleAppointment().then(response => {
        ...
        appointmentScheduled({
        "appointment_date": '12-12-2020 21:00:00+0000',
        "appointment_with": 'Robert'
        })
        ...
    })
...

API Documentation

validateUser
```
validateUser(): Promise<JSON or Undefined>
```
validateUser receives userId, campaignUuid and accessToken from the localStorage and checks if the values are present. If present, it proceeds to the user validation. If any of the values are not present, it throws an error and returns the user back to the co-branded page url or the Marketplace url.
```
  /**
  *
  * @returns {Promise<Object>} - the user validation response
  */
  function validateUser()
```

offerRedeemed

offerRedeemed(): Promise<JSON or Error>

To redeem offer, call the method offerRedeemed when the merchant website gets a payment callback with the user's payment info. The offerRedeemed method accepts a paymentInfo parameter which contains payment information.

  /**
  *
  * @ param {Object} 
  * paymentInfo: {
  *   "order_cost": <String>,
  *   "currency": <String>,
  *   "metadata": <Object>
  * }
  */
  function offerRedeemed(paymentInfo)

where paymentInfo is of type JSON, the paymentInfo object also accepts metadata of type JSON.

  {
    ...
    ...
    "metadata": {
      "date_of_payment": <String>,
      "mode_of_payment": <String>
    }
  }

appointmentScheduled

appointmentScheduled(): Promise<JSON or Error>

To schedule an appointment, call the method appointmentScheduled. The appointmentScheduled method accepts an appointmentInfo parameter containing the appointment information.

  /**
  *
  * @param {Object} 
  * appointmentInfo: {
  *   "appointment_date": <String>,
  *   "appointment_with": <String>
  * }
  */
  function appointmentScheduled(appointmentInfo)

where appointmentInfo is of type JSON

Troubleshooting

Here are some solutions to common errors that are encountered when integrating with the SDK. If you don't find an answer here you you can let us know about the problem.

What does the CORS error mean?

"Access to XMLHttpRequest at 'https://api.aperks.kun.ai/validate' from origin has been blocked by CORS policy: Response to preflight request doesn't pass access control check: No 'Access-Control-Allow-Origin' header is present on the requested resource."

If you see a CORS error, please reach out to the PM and Engineering Lead from Amex with your URLs to be whitelisted.

What does the error message “Please check the keys” mean?

If you received this error message when testing your end-to-end flow, it means you have not used the correct API keys as per the environment. To resolve this error, please verify the keys used to initialize the configuration are the correct keys for that mode, i.e. development, qa, production.

What does the error message “Invalid request signatures!” mean?

If you received this error message, it means the token exchange API failed. This error will occur due to invalid API keys or campaign uuid. To resolve this error, please verify the keys or uuid used to initialize the configuration are the correct keys for that mode, i.e. development, qa, production.

In some instances, the error may also occur due to an old build served after a recent release to production. To resolve the error, please contact the Amex Perks team so we can purge the cache for your campaign URL.

apisauce crypto-es lodash

3 years ago

3 years ago

4 years ago

4 years ago

4 years ago

4 years ago