@securecall/client-component
Version:
SecureCall Core Web Component
289 lines (194 loc) • 18.9 kB
Markdown
# SecureCall Client Web Component #
This component provides the client user interface for taking secure payments with SecureCall.
It provides the following
* provides visual feedback to a user for secure data entry
* allows data entry of other fields required to submit transactions
* interfaces with the SecureCall Client API
* emits Events on session, authentication and configuration updates
* has helper functions for each of the APIs
* allows customisation via functions called on the component
## Install ##
NOTE: It is important to specify a version when using this component in a production environments.
We make every effort to ensure backwards compatibility, but versions may include or remove features.
Ensure your production environments are stable by specifying a version and testing any new release thoroughly before making it live for your agents.
If you are developing a project using NPM then you can install the component using npm
`npm install --save /client-component@<version>`
If you are wrapping the component in a web page, then you can include it using something like the following:
`<script type="module" src="https://cdn.jsdelivr.net/npm/@securecall/client-component/dist/client-component/client-component.esm.js"></script>`
This would use the latest version from the jsdelivr CDN. As stated above, pinning a version would be a better strategy for production like this:
`<script type="module" src="https://cdn.jsdelivr.net/npm/@securecall/client-component@1.0.2/dist/client-component/client-component.esm.js"></script>`
You can also download the package and host it locally to get the best speed and reliability.
## Usage ##
### Minimal Example ###
```
<!DOCTYPE html>
<html lang="en-AU">
<head>
<script type="module" src="https://cdn.jsdelivr.net/npm/@securecall/client-component/dist/client-component/client-component.esm.js"></script>
</head>
<body>
<div id="web-component">
<securecall-client id="securecall" theme="dark" api-location="https://client.au.securcallapi.cloud"></securecall-client>
</div>
<script>
document.addEventListener('DOMContentLoaded', () => {
const securecall = document.getElementById('securecall');
securecall.addEventListener('authenticationSuccess', () => {
console.log('Authentication success');
});
securecall.addEventListener('authenticationFailure', () => {
console.log('Authentication failed');
});
})
</script>
</body>
</html>
```
The minimal example will make connection to the SecureCall Client API and will show authenticationFailure in the console log.
# Client Component #
## Properties
| Property | Attribute | Description | Type | Default |
|----------------------------|------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------|-----------------|
| `apiLocation` | `api-location` | The URL of the SecureCall Client API for your region. This would be one of `https://client.au.securecallapi.cloud`, `https://client.us.securecallapi.cloud` or `https://client.uk.securecallapi.cloud` | `string` | `window.origin` |
| `awaitActiveCall` | `await-active-call` | Set to true to disable the Secure button. Used by telephony integrations | `boolean` | `false` |
| `hideSecureButton` | `hide-secure-button` | Set to true to hide the secure button. Typically used if the secure method will be called instead | `boolean` | `false` |
| `displayTransactionResult` | `display-transaction-result` | Set to false to not show the transaction result view at all | `boolean` | `true` |
| `theme` | `theme` | Sets the theming of the component | `"dark" \| "light"` | `'light'` |
| `switchHint` | `switch-hint` | Suggests to SecureCall what type of telephony to use. Only relevant at the moment for WebexCC where it should be set to 'webexcc' when using the securecall-webexcc-telephony widget in the desktop layout | `string` | |
## Events
| Event | Description | Type |
|-------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------|
| `authenticationFailure` | Authentication with SecureCall has failed. The reason and numbers of times it has failed are passed in the event. This will be the first event thrown and usually where the authenticate method is called from. | `CustomEvent<object>` |
| `authenticationSuccess` | Authentication with SecureCall has succeeded. The component is now live. | `CustomEvent<string>` |
| `configurationChanged` | A configuration event was sent by SecureCall. | `CustomEvent<string>` |
| `callEnded` | A secured call has ended. | `CustomEvent<string>` |
| `callSecured` | The current call has been secured (true) or unsecured (false) | `CustomEvent<boolean>` |
| `loggedOut` | The user has logged out of SecureCall | `CustomEvent<boolean>` |
| `transactionSubmitted` | The transaction has been submitted to the backend. | `CustomEvent<ITransactionValues>` |
| `transactionSubmitting` | The backend has sent the transaction to the payment gateway. | `CustomEvent<ITransactionData>` |
| `transactionSuccess` | The transaction has succeeded. The result is in the event detail. | `CustomEvent<ITransactionData>` |
| `transactionFailure` | The transaction has failed. The reason is in the event detail. | `CustomEvent<ITransactionData>` |
## Methods
### `authenticate(username?: string, password?: string, useCookie?: boolean) => Promise<void>`
Authenticate the user to SecureCall. This is required before any of the functionality will work.
#### Parameters
| Name | Type | Description |
|-------------|-----------|---------------------------------------------------------------------------------------------------------------------|
| `username` | `string` | The email address of the user |
| `password` | `string` | The API key, telephony organisation ID, or password of the user. Which one to use depends on your SecureCall setup. |
| `useCookie` | `boolean` | Do you want to use a cookie to keep the authentication active? Typically this is false |
#### Returns
Type: `Promise<void>`
### `logout() => Promise<void>`
Logs the user out of SecureCall
#### Returns
Type: `Promise<void>`
### `secure() => Promise<void>`
Secures the current active call. This can be used when integrating with a CRM rather than using the button in the component.
#### Returns
Type: `Promise<void>`
### `submitAnotherTransaction(data: ITransactionValues) => Promise<boolean>`
This allows another transaction to be submitted without user input.
For example, you may need to submit two transactions, one after another. The user can use the submit button to trigger the first transaction, and the second could use this method in the transactionSuccess event handler.
#### Parameters
| Name | Type | Description |
|--------|----------------------|-------------------------|
| `data` | `ITransactionValues` | The transaction details |
#### Returns
Type: `Promise<boolean>`
### `triggerAnotherTransaction(resetTransactionDetails?: boolean, resetCardFields?: string[]) => Promise<void>`
Resets the component back to the transaction screen for the user to input a new transaction. Which fields are reset can be controlled by the parameters.
#### Parameters
| Name | Type | Description | Defaults |
|---------------------------|------------|------------------------------------------------------------------------------------------------------------------|----------|
| `resetTransactionDetails` | `boolean` | Resets all the transaction fields when true | false |
| `resetCardFields` | `string[]` | A list of secure fields to reset. Set to an empty array to not reset any of them or ['all'] to reset all of them | ['cvv'] |
#### Returns
Type: `Promise<void>`
### `updateRequestFields(updates: (arg0: any) => void) => Promise<void>`
Changes field configuration for the instance. These changes will be persistent for the duration this instance of the component is loaded.
Typically, this will be used to set the fields that won't change between calls or transactions.
For example, to add a new field called currency which is a drop-down box and is available for every transaction.
This also sets the amount and paymentReference fields to readOnly so they can be set by an external process for each transaction using updateTransactionRequestFields()
```javascript
await myComponent.updateRequestFields(f => {
f.addNewField('currency', {
order: 15,
mapping: 'metadata.currency',
label: 'Currency',
component: 'select',
readOnly: false,
hidden: false,
possibleValues: {gbp: 'GBP', usd: 'USD', eur: 'EUR'}
});
f.amount.readOnly = true;
f.paymentReference.readOnly = true;
})
```
#### Parameters
| Name | Type | Description |
| --------- | --------------------- | ----------- |
| `updates` | `(arg0: any) => void` | |
#### Returns
Type: `Promise<void>`
### `updateSessionRequestFields(updates: (arg0: any) => void) => Promise<void>`
Does the same as updateRequestFields but the changes wont last once the call has ended
#### Parameters
| Name | Type | Description |
| --------- | --------------------- | ----------- |
| `updates` | `(arg0: any) => void` | |
#### Returns
Type: `Promise<void>`
### `updateTransactionRequestFields(updates: (arg0: any) => void) => Promise<void>`
Does the same as updateRequestFields but affects the current transaction
Following the example in updateRequestFields, this sets the currency, amount and paymentReference
```javascript
await myComponent.updateTransactionRequestFields(f => {
f.currency.value = 'eur';
f.amount.value = 13.45;
f.paymentReference.value = 'ref-' + Date.now();
})
```
#### Parameters
| Name | Type | Description |
| --------- | --------------------- | ----------- |
| `updates` | `(arg0: any) => void` | |
#### Returns
Type: `Promise<void>`
### `updateResponseFields(updates: (arg0: any) => void) => Promise<void>`
Set the configuration for the fields shown once a transaction is successful or unsuccessful.
If you dont want to show the "Another Transaction" button, you can use this method to do that
```javascript
await myComponent.updateResponseFields(f => {
f.anotherTransaction.showOnSuccess = false
f.anotherTransaction.showOnFailure = false
})
```
#### Parameters
| Name | Type | Description |
|-----------|-----------------------|-------------|
| `updates` | `(arg0: any) => void` | |
#### Returns
Type: `Promise<void>`
## Fields ##
| Name | Type | Description |
|-------------------|------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| order | number | The order of the field in the display |
| value | string | The value that will be used to submit to SecureCall |
| readOnly | boolean | Is the field readOnly or can the user enter data into it? |
| hidden | boolean | Is the field visible? Hidden fields dont count toward form validity so they should have the correct value applied or the transaction may fail |
| valid | boolean | This attribute is set by the field entry so there is little point setting it |
| possibleValues | Record<string, string> | An object with potential values to choose from. The key is the value that will be used and the value is the label that will be displayed to the user. The select and radio fields expect an object |
| mapping | string | Helps construct the submission request to SecureCall. Typically this will be "metadata.xxx" for a new field. |
| label | string | The label for the field displayed to the User |
| component | string | The type of field to display. The choices are radio, string, currency and select. |
| min | number | If the field supports it, this is the minimum value or length to be considered valid |
| max | number | If the field supports it, this is the maximum value or length to be considered valid |
| active | boolean | This is only used by the secure fields to show which one is active at this point in time. Dont bother setting this. |
| placeholder | string | Displays a placeholder in the field if the field supports it |
| hideRelatedFields | Record<string, object> | This can be used to change which fields are displayed when another value is chosen. Used by the radio field type. |
| secure | boolean | Flags this field is a secure field where the data entry will come from the customer |
| optional | boolean | Flags this field is optional and will validate if empty. Only applies to string fields currently |
### `addNewField(name: string, config?: object) => void`
Called within one of the updateRequestField functions to add a new field to be displayed and possibly entered.
The configuration can be passed in the config object or manipulated later