From dec6ce7e547719a7d18d7c22ceaca286d5e3724d Mon Sep 17 00:00:00 2001 From: Drew Hudec Date: Tue, 10 Jan 2023 09:13:59 -0500 Subject: [PATCH] feat: Updates Android SDK docs and adds card brand details (#27) * Documenting isComplete, isEmpty, isMaskSatisfied on Android * Extracting CardBrands component to share docs between sdks and updating some js elements docs --- docs/sdks/_card-brands.mdx | 23 ++++++++++++ docs/sdks/mobile/android/events.mdx | 13 ++++--- docs/sdks/mobile/android/types.mdx | 56 +++++++++++++--------------- docs/sdks/web/javascript/methods.mdx | 2 +- docs/sdks/web/javascript/options.mdx | 23 ++---------- 5 files changed, 61 insertions(+), 56 deletions(-) create mode 100644 docs/sdks/_card-brands.mdx diff --git a/docs/sdks/_card-brands.mdx b/docs/sdks/_card-brands.mdx new file mode 100644 index 00000000..6f2382b1 --- /dev/null +++ b/docs/sdks/_card-brands.mdx @@ -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 | + + + Some card brands have issued card numbers with multiple lengths. The Card Number Digits column + documents all acceptable card number lengths for the brand (in number of digits, excluding formatting characters). + diff --git a/docs/sdks/mobile/android/events.mdx b/docs/sdks/mobile/android/events.mdx index dcc166b1..62acebf8 100644 --- a/docs/sdks/mobile/android/events.mdx +++ b/docs/sdks/mobile/android/events.mdx @@ -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` | 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` | A list of [EventDetails](#eventdetails) included with this event | ### EventDetails diff --git a/docs/sdks/mobile/android/types.mdx b/docs/sdks/mobile/android/types.mdx index 3898c6db..b3b78e90 100644 --- a/docs/sdks/mobile/android/types.mdx +++ b/docs/sdks/mobile/android/types.mdx @@ -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 @@ -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 @@ -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. + + + +#### 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 diff --git a/docs/sdks/web/javascript/methods.mdx b/docs/sdks/web/javascript/methods.mdx index b1dca343..cb661ea4 100644 --- a/docs/sdks/web/javascript/methods.mdx +++ b/docs/sdks/web/javascript/methods.mdx @@ -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)
[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. | diff --git a/docs/sdks/web/javascript/options.mdx b/docs/sdks/web/javascript/options.mdx index 0485fef2..6706bdaf 100644 --- a/docs/sdks/web/javascript/options.mdx +++ b/docs/sdks/web/javascript/options.mdx @@ -3,6 +3,7 @@ sidebar_label: Options --- import { Alert, Alerts } from "@site/src/components/shared/Alert"; +import CardBrands from "@site/docs/sdks/_card-brands.mdx"; # Elements Options @@ -20,7 +21,7 @@ You can customize the behavior of your Elements using the following options: | `transform` | false | _RegExp_ | true | [`text`](/docs/sdks/web/javascript/types#text-element) | [`RegExp` object or array](#transform) used to modify user input before [tokenization](/docs/sdks/web/javascript/methods#tokenization) | | `password` | false | _boolean_ | true | [`text`](/docs/sdks/web/javascript/types#text-element) | Boolean used to set the text element input type as [password](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/password) | | `iconPosition` | false | _string_ | true | [`cardNumber`](/docs/sdks/web/javascript/types#card-number-element) | String used to determine the position of the card element icon. Expected values are: `left` (default), `right` or `none`. | -| `cardBrand` | false | _string_ | true | [`cardVerificationCode`](/docs/sdks/web/javascript/types#card-verification-code-element) | [String](#card-brands) used to determine proper input format and default placeholder/aria-label | +| `cardBrand` | false | _string_ | true | [`cardVerificationCode`](/docs/sdks/web/javascript/types#card-verification-code-element) | [Brand identifier](#card-brands) used to determine proper input format and default placeholder/aria-label | | `value` | false | _string_ | true | All | Sets a static value for the element input. | @@ -75,7 +76,7 @@ var cardElement = BasisTheory.createElement("card", { |------------|----------|----------|------------------------------------------------------------------------------------| | `fonts` | false | _array_ | Array of Google Fonts URLs | | `base` | false | _object_ | Base variant style - all other variant styles inherit from this one | -| `complete` | false | _object_ | Variant style applied when the element input has valid value | +| `complete` | false | _object_ | Variant style applied when the element input is complete | | `empty` | false | _object_ | Variant style applied when the element input has no value | | `invalid` | false | _object_ | Variant style applied when the element input has invalid value | @@ -265,23 +266,7 @@ var phoneNumberElement = BasisTheory.createElement("text", { ## Card Brands -The following list maps supported Card Brands to their values: - -| Brand | Value | -|------------------|--------------------| -| American Express | `american-express` | -| Diners Club | `diners-club` | -| Discover | `discover` | -| Elo | `elo` | -| Hiper | `hiper` | -| HiperCard | `hipercard` | -| JCB | `jcb` | -| Maestro | `maestro` | -| Mastercard | `mastercard` | -| MIR | `mir` | -| UnionPay | `unionpay` | -| Visa | `visa` | -| Unknown | `unknown` | + If you don't see the card brand you're looking for, please{" "}