Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: documenting android proxy and get a token services #50

Merged
merged 6 commits into from
Jan 26, 2023
Merged

feat: documenting android proxy and get a token services #50

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
a99782b
feat: documenting android proxy and get a token services
jleon15 Jan 25, 2023
71cf9da
documenting set value ref for exp date element
jleon15 Jan 25, 2023
5606f5a
some rewording
jleon15 Jan 26, 2023
e252820
some rewording
jleon15 Jan 26, 2023
1b3bb17
renaming iodispatcher
jleon15 Jan 26, 2023
cd61599
some rewording
jleon15 Jan 26, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 56 additions & 1 deletion docs/sdks/mobile/android/services.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
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.
Comment on lines +76 to +86
Copy link
Contributor

@dhudec dhudec Jan 26, 2023 •
edited
Loading

Choose a reason for hiding this comment

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

This should link to https://developers.basistheory.com/docs/guides/govern/sessions

Maybe at the end, add: "To learn more about how to authorize a session, read our guide Access Data Using Sessions"


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. |
Comment on lines +127 to +128
Copy link
Contributor

@dhudec dhudec Jan 26, 2023 •
edited
Loading

Choose a reason for hiding this comment

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

I'm having this thought late here in the docs, but technically, query params and headers can be repeated with the same name, so it might be more correct to make these some sort of array of pairs instead of maps. We may never run into that use case from here though, but if we do that would be a breaking change...

Copy link
Contributor Author

Choose a reason for hiding this comment

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

interesting, the java sdk receives a map for headers but for query params it does receive a list of pairs instead

| `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
Open in desktop
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 getting into compliance scope.
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
you can reference data without touching the plaintext value and getting into compliance scope.
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