Skip to content

Commit

Permalink
feat: documenting android proxy and retrieve token services (#50)
Browse files Browse the repository at this point in the history
  • Loading branch information
@jleon15
jleon15 authored Jan 26, 2023
1 parent 5382ab0 commit 9222cf4
Show file tree
Hide file tree
Showing 2 changed files with 80 additions and 11 deletions.
59 changes: 57 additions & 2 deletions docs/sdks/mobile/android/services.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ A new instance of the `BasisTheoryElements` service can be configured using the
val bt = BasisTheoryElements.builder()
.apiUrl("https://api.basistheory.com") // optional
.apiKey(myApiKey)
.ioDispatcher(myDispatcher) // optional
.dispatcher(myDispatcher) // optional
.build()
```

Expand Down Expand Up @@ -54,7 +54,7 @@ needing to touch the raw data directly.
### createToken

This function wraps the [create token API endpoint](/docs/api/tokens/tokenize#create-token) to
be able to create a single strongly typed token. It also provides added support for referencing
create a single strongly typed token. It also provides added support for referencing
instances of Elements within your request payload.

```kotlin showLineNumbers
Expand All @@ -72,3 +72,58 @@ val createTokenResponse = bt.createToken(CreateTokenRequest().apply {
As you can see from this example, the `createToken` function is capable of resolving the raw data
from references to Element inputs. This enables your application to tokenize sensitive data values without
needing to touch the raw data directly.

### createSession

To retrieve sensitive data on Android, you'll need to create a `session` and use its `sessionKey` for making requests securely.
To accomplish this, simply call the `createSession` function like this:

```kotlin showLineNumbers
val session = bt.createSession()
```

This returns a [CreateSessionResponse](/docs/api/applications/sessions#create-session-response-object)
which contains a `nonce` that needs to be used to [authorize the session](/docs/api/applications/sessions#authorize-session) before using it.

To learn more about how to authorize a session, read our guide [Access Data Using Sessions](/docs/guides/govern/sessions).

### getToken

This function wraps the [get a token API endpoint](/docs/api/tokens/#get-a-token) to
retrieve a single strongly typed token. It then transforms the token's data to
value references which you can use to [set the value](/docs/sdks/mobile/android/types#methods) of your elements without touching
the plaintext value and pulling your application into compliance scope.

```kotlin showLineNumbers
val getTokenResponse = bt.getToken("<tokenId>")
```

### proxy

This function receives a [ProxyRequest](/docs/sdks/mobile/android/services#proxyrequest) and wraps the [proxy API endpoint](/docs/api/proxies/invoke-proxy) to
proxy a request to a third party API. It then transforms the response to
value references which you can then use to [set the value](/docs/sdks/mobile/android/types#methods) of your elements without touching
the plaintext value and pulling your application into compliance scope.

```kotlin showLineNumbers
val proxyResponse = bt.proxy.post(proxyRequest)
```

#### Methods Supported

| Signature | Description |
|----------------------------------------------------------------------------|----------------------------------|
| `get(proxyRequest: ProxyRequest, apiKeyOverride: String? = null): Any?` | Performs a proxy GET request. |
| `post(proxyRequest: ProxyRequest, apiKeyOverride: String? = null): Any?` | Performs a proxy POST request. |
| `put(proxyRequest: ProxyRequest, apiKeyOverride: String? = null): Any?` | Performs a proxy PUT request. |
| `patch(proxyRequest: ProxyRequest, apiKeyOverride: String? = null): Any?` | Performs a proxy PATCH request. |
| `delete(proxyRequest: ProxyRequest, apiKeyOverride: String? = null): Any?` | Performs a proxy DELETE request. |

#### ProxyRequest

| Attribute | Required | Type | Default | Description |
|---------------|----------|------------------------|--------------|---------------------------------------------------------------------------------------------------------|
| `path` | false | _String?_ | `null` | The sub-path of the HTTP URL. |
| `queryParams` | false | _Map<String, String>?_ | `emptyMap()` | Map of query parameters to include in the request. |
| `headers` | false | _Map<String, String>?_ | `emptyMap()` | Map of headers to include in the request. |
| `body` | false | _Any?_ | `null` | The request body. Can be an object, array, or any primitive type such as an integer, boolean, or string |
32 changes: 23 additions & 9 deletions docs/sdks/mobile/android/types.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -58,17 +58,23 @@ The following additional properties are supported when programmatically interact

#### Methods

| Signature | Description |
|-----------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `addBlurEventListener(listener: (BlurEvent) -> Unit)` | Adds a listener for any [BlurEvents](/docs/sdks/mobile/android/events#blurevent) raised by this element. |
| `addChangeEventListener(listener: (ChangeEvent) -> Unit)` | Adds a listener for any [ChangeEvents](/docs/sdks/mobile/android/events#changeevent) raised by this element. |
| `addFocusEventListener(listener: (FocusEvent) -> Unit)` | Adds a listener for any [FocusEvents](/docs/sdks/mobile/android/events#focusevent) raised by this element. |
| `setText(value: String?)` | Sets the text value for the element. Note that a getter is not exposed on the TextElement to retrieve the underlying text value. |
| `setValueRef(element: TextElement)` | Binds the provided `element: TextElement` instance as a value source for this element, keeping the value of this element in sync with any changes made to the other element. |
| Signature | Description |
|-------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `addBlurEventListener(listener: (BlurEvent) -> Unit)` | Adds a listener for any [BlurEvents](/docs/sdks/mobile/android/events#blurevent) raised by this element. |
| `addChangeEventListener(listener: (ChangeEvent) -> Unit)` | Adds a listener for any [ChangeEvents](/docs/sdks/mobile/android/events#changeevent) raised by this element. |
| `addFocusEventListener(listener: (FocusEvent) -> Unit)` | Adds a listener for any [FocusEvents](/docs/sdks/mobile/android/events#focusevent) raised by this element. |
| `setText(value: String?)` | Sets the text value for the element. Note that a getter is not exposed on the TextElement to retrieve the underlying text value. |
| `setValueRef(elementValueReference: ElementValueReference)` | Sets the element's text to the value referenced by the provided ElementValueReference. |
| `setValueRef(element: TextElement)` | Binds the provided `element: TextElement` instance as a value source for this element, keeping the value of this element in sync with any changes made to the other element. |

<Alert>
When using <code>setValueRef</code> to keep a <code>TextElement</code> in sync with another element, it is strongly recommended that
you make the dependent element readonly by also setting <code>isEditable=false</code>.
<code>ElementValueReference</code> is a class that stores a reference to a value which can only be accessed by BasisTheoryElements, so that
you can reference data without touching the plaintext value and pulling your application into compliance scope.
</Alert>

<Alert>
When using <code>setValueRef</code> to keep a <code>TextElement</code> in sync with another element, or to set the text of an element, it is strongly recommended that
you make the element that is being acted upon <code>readonly</code>. This is possible by setting <code>isEditable=false</code>.
</Alert>

#### XML Attributes
Expand Down Expand Up @@ -232,6 +238,14 @@ By default, this element is configured with:
This component fully supports the same [style customizations](/docs/sdks/mobile/android/options#styling) to match your branding
that are supported on the base [TextElement](#textelement).

### Additional Methods Supported

| Signature | Description |
|--------------------------------------------------------------------------------|---------------------------------------------------------------------------------------|
| `month(): ElementValueReference` | Returns a value reference you can use when tokenizing without touching the raw value. |
| `year(): ElementValueReference` | Returns a value reference you can use when tokenizing without touching the raw value. |
| `setValueRef(monthRef: ElementValueReference, yearRef: ElementValueReference)` | Sets the expiration date to the value referenced by the provided references. |

## CardVerificationCodeElement

The `CardVerificationCodeElement` can be used to securely collect credit card CVC values within
Expand Down

1 comment on commit 9222cf4

@vercel
Copy link

@vercel vercel bot commented on 9222cf4 Jan 26, 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-git-master-basis-theory.vercel.app
developers.basistheory.com
developers-basistheory-com-basis-theory.vercel.app

Please sign in to comment.