Skip to content

Commit

Permalink
feat: Updates Android SDK docs and adds card brand details (#27)
Browse files Browse the repository at this point in the history 
* Documenting isComplete, isEmpty, isMaskSatisfied on Android

* Extracting CardBrands component to share docs between sdks and updating some js elements docs
  • Loading branch information
@dhudec
dhudec authored Jan 10, 2023
1 parent b015192 commit dec6ce7
Show file tree
Hide file tree
Showing 5 changed files with 61 additions and 56 deletions.
23 changes: 23 additions & 0 deletions docs/sdks/_card-brands.mdx
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
import { Alert } from "@site/src/components/shared/Alert";

Supported card brands are defined in the table below:

| Brand | Identifier | Card Number Digits | CVC Digits |
|------------------|--------------------|--------------------|------------|
| American Express | `american-express` | 15 | 4 |
| Diners Club | `diners-club` | 14, 16, 19 | 3 |
| Discover | `discover` | 16, 19 | 3 |
| Elo | `elo` | 16 | 3 |
| Hiper | `hiper` | 16 | 3 |
| HiperCard | `hipercard` | 16 | 3 |
| JCB | `jcb` | 16-19 | 3 |
| Maestro | `maestro` | 12-19 | 3 |
| Mastercard | `mastercard` | 16 | 3 |
| MIR | `mir` | 16-19 | 3 |
| UnionPay | `unionpay` | 14-19 | 3 |
| Visa | `visa` | 16, 18, 19 | 3 |

<Alert>
Some card brands have issued card numbers with multiple lengths. The <code>Card Number Digits</code> column
documents all acceptable card number lengths for the brand (in number of digits, excluding formatting characters).
</Alert>
13 changes: 7 additions & 6 deletions docs/sdks/mobile/android/events.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,12 +13,13 @@ Raised whenever the element's value is changed, upon each keypress and after pas

### Schema

| Property | Type | Description |
|------------|----------------------|---------------------------------------------------------------------------------------------|
| isComplete | `Boolean` | Whether the element has been completely filled (as specified by the [mask](/docs/sdks/mobile/android/options#mask)) |
| isEmpty | `Boolean` | Whether the element is empty |
| isValid | `Boolean` | The result of the [validator](/docs/sdks/mobile/android/options#validator), or `true` if no validator is specified |
| details | `List<EventDetails>` | A list of [EventDetails](#eventdetails) included with this event |
| Property | Type | Description |
|-----------------|----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| isComplete | `Boolean` | Whether this element satisfies the mask and validator, i.e. it is ready to be tokenized. |
| isEmpty | `Boolean` | Whether this element is empty. |
| isMaskSatisfied | `Boolean` | Whether this element satisfies the length and format requirements of the [mask](/docs/sdks/mobile/android/options#mask), if defined. Defaults to `true` if this element does not have a mask. |
| isValid | `Boolean` | The result of this element's [validator](/docs/sdks/mobile/android/options#validator), if defined. Defaults to `true` if this element does not have a validator. |
| details | `List<EventDetails>` | A list of [EventDetails](#eventdetails) included with this event |

### EventDetails

Expand Down
56 changes: 26 additions & 30 deletions docs/sdks/mobile/android/types.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ sidebar_label: Types
---

import { Alert } from "@site/src/components/shared/Alert";
import CardBrands from "@site/docs/sdks/_card-brands.mdx";

# Android Element Types

Expand Down Expand Up @@ -42,14 +43,18 @@ The following additional properties are supported when programmatically interact
| Name | Type | Description |
|---------------------|--------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| hint | `String` | Placeholder text to display within the element when empty. |
| isComplete | `Boolean` | Whether this element satisfies the mask and validator, i.e. it is ready to be tokenized. |
| isEditable | `Boolean` | Whether this element is editable or readonly. |
| isEmpty | `Boolean` | Whether this element is empty. |
| isMaskSatisfied | `Boolean` | Whether this element satisfies the length and format requirements of the [mask](/docs/sdks/mobile/android/options#mask), if defined. Defaults to `true` if this element does not have a mask. |
| isValid | `Boolean` | The result of this element's [validator](/docs/sdks/mobile/android/options#validator), if defined. Defaults to `true` if this element does not have a validator. |
| keyboardType | `KeyboardType` | The type of keyboard to display when editing. Supported values are `KeyboardType.TEXT` and `KeyboardType.NUMBER`. |
| mask | `ElementMask` | Restricts and formats input entered into this Element. See the [Mask](/docs/sdks/mobile/android/options#mask) options for details. |
| removeDefaultStyles | `Boolean` | Removes the default Android styling on the underlying EditText. Defaults to `true`. |
| textColor | `Int` | A color value in the form `0xAARRGGBB`. Do not pass a resource ID. To get a color value from a resource ID, call [getColor](https://developer.android.com/reference/android/content/res/TypedArray#getColor(int,%20int)). |
| textSize | `Float` | The font size, in pixels. |
| transform | `ElementTransform` | Transforms the value of this Element prior to tokenization. See the [Transform](/docs/sdks/mobile/android/options#transform) options for details. |
| validator | `ElementValidator` | Validates the value of this Element within ChangeEvents. See the [Validator](/docs/sdks/mobile/android/options#validator) options for details. |
| validator | `ElementValidator` | Validates the value of this Element. See the [Validator](/docs/sdks/mobile/android/options#validator) options for details. |

#### Methods

Expand Down Expand Up @@ -141,46 +146,37 @@ that are supported on the base [TextElement](#textelement).

### Card Brands

The first digits of the card number are analyzed to determine the card brand, which is made available
to your application via the property:
The first several digits of the card number are analyzed as the user is typing to determine the card brand.
The brand is used to automatically set a [mask](/docs/sdks/mobile/android/options#mask) to a brand-specific format.
If the [CardNumberElement](#cardnumberelement) is bound to a [CardVerificationCodeElement](#cardverificationcodeelement),
a mask is also automatically set on the `CardVerificationCodeElement` based on the brand's CVC length requirements.

<CardBrands />

#### CardMetadata

The brand details and other card metadata are made available to your application within the
`cardMetadata` property on the `CardNumberElement`:

| Name | Type | Description |
|--------------|----------------|--------------------------------------------------------|
| cardMetadata | `CardMetadata` | Gets metadata about the card, derived from user input. |

#### CardMetadata
The `CardMetadata` object contains the properties:

| Name | Type | Description |
|------------|-----------|-------------------------------------------------------------------|
| brand | `String` | The card [brand identifier](#brand-identifiers) |
| cardMask | `String` | The card number mask corresponding to this card brand |
| cvcMask | `String` | The CVC mask corresponding to this card brand |
| isComplete | `Boolean` | Whether this card number is complete for this brand |
| bin | `String` | The first 6 digits of the card number if complete, otherwise null |
| last4 | `String` | The last 4 digits of the card number if complete, otherwise null |

#### Brand Identifiers

- `visa`
- `mastercard`
- `americanExpress`
- `dinersClub`
- `discover`
- `jcb`
- `unionPay`
- `maestro`
- `elo`
- `mir`
- `hiper`
- `hipercard`
| Name | Type | Description |
|-------|----------|-------------------------------------------------------------------|
| brand | `String` | The card [brand identifier](#card-brands) |
| bin | `String` | The first 6 digits of the card number if complete, otherwise null |
| last4 | `String` | The last 4 digits of the card number if complete, otherwise null |

### ChangeEvent Details

The `CardNumberElement` emits [ChangeEvents](/docs/sdks/mobile/android/events#changeevent) that may contain several types of [EventDetail](/docs/sdks/mobile/android/events#eventdetails) records.

- `cardBrand`: Contains the [brand identifier](#brand-identifiers) for the card brand. Only included once enough digits are entered to determine a card brand.
- `bin`: Contains the first 6 digits of the card number. Only included for complete card numbers satisfying the brand-specific mask.
- `last4`: Contains the last 4 digits of the card number. Only included for complete card numbers satisfying the brand-specific mask.
- `cardBrand`: Contains the card [brand identifier](#card-brands). Only included once enough digits are entered to determine a card brand.
- `cardBin`: Contains the first 6 digits of the card number. Only included for complete card numbers satisfying the brand-specific mask.
- `cardLast4`: Contains the last 4 digits of the card number. Only included for complete card numbers satisfying the brand-specific mask.

## CardExpirationDateElement

Expand Down
2 changes: 1 addition & 1 deletion docs/sdks/web/javascript/methods.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,7 @@ cardElement.on("change", (changeEvent) => {

| Attribute | Type | Eligible Elements | Description |
|-------------|-----------|----------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `complete` | _boolean_ | All | If the element value is well-formed and is ready to be submitted. |
| `complete` | _boolean_ | All | Whether this element satisfies the mask and is valid, i.e. it is ready to be tokenized. |
| `empty` | _boolean_ | All | Whether the element is empty. Multi-input Elements will be `empty` only if all inputs are. |
| `errors` | _array_ | All | Array of [FieldError](#fielderror). |
| `cardBrand` | _string_ | [card](/docs/sdks/web/javascript/types#card-element)<br/>[cardNumber](/docs/sdks/web/javascript/types#card-number-element) | (Optional) The credit card [brand](/docs/sdks/web/javascript/options#card-brands) (e.g. `'american-express'`, `'visa'`, `'unknown'`). The value defaults to `'unknown'` until a card brand is recognized. |
Expand Down
Loading

1 comment on commit dec6ce7

@vercel
Copy link

@vercel vercel bot commented on dec6ce7 Jan 10, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Successfully deployed to the following URLs:

developers-basistheory-com – ./

developers-basistheory-com-basis-theory.vercel.app
developers-basistheory-com-git-master-basis-theory.vercel.app
developers.basistheory.com

Please sign in to comment.