feat: Adds Elements concept page (#55)

Basis-Theory · Jan 31, 2023 · c915033 · c915033 · vercel · Jan 31, 2023
1 parent 8a0ed52
commit c915033
Show file tree

Hide file tree

Showing 8 changed files with 174 additions and 140 deletions.
diff --git a/docs/concepts/access-controls.mdx b/docs/concepts/access-controls.mdx
@@ -206,7 +206,7 @@ beyond collecting data within your frontend applications.
 
 Sessions are a good fit for the following use cases:
 
-- Revealing tokens in a front end application in plaintext (see [reveal sensitive data with Elements](/docs/sdks/web/javascript#reveal-sensitive-data))
+- Revealing tokens in a front end application in plaintext (see [reveal sensitive data with Elements](/docs/concepts/elements#reveal-sensitive-data))
 - Calling the proxy or reactors from your frontend application
 - Restricting the access granted to public API keys to prevent unauthorized use
   - Only allow tokens to be created by authenticated users in your system

diff --git a/docs/concepts/elements.mdx b/docs/concepts/elements.mdx
@@ -0,0 +1,94 @@
+---
+title: Elements
+sidebar_label: Elements
+---
+
+import { SdkCard } from "@site/src/components/sdks/SdkCard";
+import { SDK } from "@site/src/components/types";
+
+# Elements
+
+Basis Theory Elements are simple and secure inputs that empower developers to collect sensitive data
+from users or to reveal sensitive data back to users, all without having direct access to the plaintext data.
+This last point is key - any application code that interacts with sensitive regulated data can be subject to costly and
+time-consuming audits to prove that your application meets various compliance standards (e.g. PCI-DSS, HIPAA, SOC 2, ISO-27001).
+Using Elements can completely remove your frontend applications from compliance scope, saving your development
+team time and money.
+
+Think about it as an isolated sandbox within your frontend application that your end users are able to seamlessly
+interact with, and which securely communicates with the Basis Theory vault to tokenize or detokenize data.
+Sensitive data is not directly exposed to your application code, and only the non-sensitive token identifiers are
+exposed to be referenced within your systems.
+
+Here's how Basis Theory Elements make this possible:
+
+- Install one of our [Elements SDKs](#elements-sdks) into your web or mobile application
+- Build forms using our **Element** input components
+- Interact with the Basis Theory API using **Element** references, not plaintext data
+- Own your UI/UX by fully customizing how **Elements** are styled
+
+## Collect Sensitive Data
+
+Data entered by your end users into an **Element** is tokenized and secured within the Basis Theory vault, without your application
+needing to have direct access to this data.
+
+Our SDKs provide several types of inputs to collect various types of data, such as the [CardElement](/docs/sdks/web/javascript/types#card-element)
+for collecting credit card data and [TextElement](/docs/sdks/web/javascript/types#text-element) for collecting arbitrary textual data.
+
+Elements can be configured to support custom input masking, validation, and transformation rules to satisfy your unique requirements.
+
+To get started collecting data, check out one of our guides that best suits your use case:
+
+- [Collect Data from Web](/docs/guides/collect/collect-data-from-web)
+- [Collect Data with React](/docs/guides/collect/collect-data-with-react)
+- [Collect Data with Android](/docs/guides/collect/collect-data-with-android)
+- [Collect Data with iOS](/docs/guides/collect/collect-data-with-ios)
+
+## Reveal Sensitive Data
+
+Tokens stored within the Basis Theory Vault can be securely revealed to end users without accessing the plaintext
+data directly within your application code.
+
+Using one of our [SDKs](#elements-sdks), sensitive data can be securely retrieved and applied to one or more Elements within your UI.
+The SDK will manage encapsulating the sensitive data so that your application can reference these value without having direct access to it.
+
+To get started revealing sensitive data to your users, check out our guides:
+
+- [Reveal Data on Web](/docs/sdks/web/javascript/methods#detokenization)
+- [Reveal Data on Android](/docs/sdks/mobile/android/services#gettoken)
+- [Reveal Data on iOS](/docs/sdks/mobile/ios/services#proxy)
+
+## Elements SDKs
+
+<SdkCard.TwoColumnLayout>
+  <SdkCard
+    href="/docs/sdks/web/javascript"
+    heading="JavaScript Elements SDK"
+    icon={SDK.JAVASCRIPT}
+    repository="basis-theory-js"
+  />
+
+  <SdkCard
+    href="/docs/sdks/web/react"
+    heading="React Elements SDK"
+    icon={SDK.REACT}
+    repository="basis-theory-react"
+  />
+
+  <SdkCard
+    href="/docs/sdks/mobile/ios"
+    heading="iOS Elements SDK"
+    sources={{
+      light: "/img/sdk/logos/apple.svg",
+      dark: "/img/sdk/logos/apple-dark.svg",
+    }}
+    repository="basistheory-ios"
+  />
+
+  <SdkCard
+    href="/docs/sdks/mobile/android"
+    heading="Android Elements SDK"
+    icon={SDK.ANDROID}
+    repository="basistheory-android"
+  />
+</SdkCard.TwoColumnLayout>
diff --git a/docs/concepts/index.mdx b/docs/concepts/index.mdx
@@ -26,55 +26,64 @@ Explore the knowledge base about the core concepts, terminology, and FAQ's relat
     column
     img={<Info />}
     href="/docs/concepts/what-are-tokens"
-    heading="What are tokens?"
+    heading="What are Tokens?"
   >
     Use tokens to secure and share your sensitive data.
   </Card>
 
-<Card
-  column
-  img={<Info />}
-  href="/docs/concepts/what-is-search"
-  heading="What is Search?"
->
-  Search your data without decrypting it.
-</Card>
+  <Card
+    column
+    img={<Info />}
+    href="/docs/concepts/what-is-search"
+    heading="What is Search?"
+  >
+    Search your data without decrypting it.
+  </Card>
 
-<Card
-  column
-  img={<Info />}
-  href="/docs/concepts/what-are-containers"
-  heading="What are Token Containers?"
->
-  Create hierarchies and classifications of your data.
-</Card>
+  <Card
+    column
+    img={<Info />}
+    href="/docs/concepts/what-are-containers"
+    heading="What are Token Containers?"
+  >
+    Create hierarchies and classifications of your data.
+  </Card>
 
-<Card
-  column
-  img={<Info />}
-  href="/docs/concepts/access-controls"
-  heading="Access Controls"
->
-  Use granular controls to limit the scope of your data.
-</Card>
+  <Card
+    column
+    img={<Info />}
+    href="/docs/concepts/access-controls"
+    heading="Access Controls"
+  >
+    Use granular controls to limit the scope of your data.
+  </Card>
 
-<Card
-  column
-  img={<Info />}
-  href="/docs/concepts/what-is-the-proxy"
-  heading="What is the Proxy?"
->
-  Send and receive sensitive data without touching it.
-</Card>
+  <Card
+    column
+    img={<Info />}
+    href="/docs/concepts/what-is-the-proxy"
+    heading="What is the Proxy?"
+  >
+    Send and receive sensitive data without touching it.
+  </Card>
 
-<Card
-  column
-  img={<Info />}
-  href="/docs/concepts/what-are-reactors"
-  heading="What are Reactors?"
->
-  Run code against your data in a secure environment.
-</Card>
+  <Card
+    column
+    img={<Info />}
+    href="/docs/concepts/what-are-reactors"
+    heading="What are Reactors?"
+  >
+    Run code against your data in a secure environment.
+  </Card>
+
+  <Card
+    column
+    img={<Info />}
+    href="/docs/concepts/elements"
+    heading="What are Elements?"
+  >
+    Collect or reveal sensitive data within your frontend applications.
+  </Card>
 
   <Card
     column

diff --git a/docs/guides/govern/sessions.mdx b/docs/guides/govern/sessions.mdx
@@ -48,7 +48,7 @@ If you do not already have a Private Application with these permissions, [click
 
 In order to have a token available to reveal to our frontend application in later steps, we will first create a token.
 For simplicity, we are creating this token through the Basis Theory API using the Private Application created above,
-however you can imagine this token could have been collected by a frontend application using [Elements](/docs/sdks/web/javascript).
+however you can imagine this token could have been collected by a frontend application using [Elements](/docs/concepts/elements).
 
 Run the following in your terminal to create the token:
 
@@ -315,17 +315,17 @@ TokensAPI.getByIdWithRequestBuilder(id: tokenId)
 </Alert>
 
 If you would like to securely display sensitive data within a frontend application while keeping your code out of compliance scope, you should use
-[Elements](/docs/sdks/web/javascript) to [reveal sensitive data](/docs/sdks/web/javascript/#reveal-sensitive-data) that was retrieved using a session.
+[Elements](/docs/concepts/elements) to [reveal sensitive data](/docs/concepts/elements#reveal-sensitive-data) that was retrieved using a session.
 Check out our guide to learn more!
 
 ## Conclusion
 
 :tada: You now know how to implement a session authorization flow within your system to start using sessions within your frontend applications!
 
-Sessions enable you to securely retrieve tokens within your frontend applications to reveal data within [Elements](/docs/sdks/web/javascript),
+Sessions enable you to securely retrieve tokens within your frontend applications to reveal data within [Elements](/docs/concepts/elements),
 or they can be used enhance the security within Public Applications when performing any token operation.
 
 ## Learn More
 
 - [Access Controls](/docs/concepts/access-controls)
-- [Reveal Data Using Elements](/docs/sdks/web/javascript/#reveal-sensitive-data)
+- [Reveal Data Using Elements](/docs/concepts/elements#reveal-sensitive-data)
diff --git a/docs/sdks/mobile/android/index.mdx b/docs/sdks/mobile/android/index.mdx
@@ -18,42 +18,18 @@ import { SDK } from "@site/src/components/types";
 
 ###
 
-Basis Theory Android Elements are simple, secure, developer-friendly inputs that empower consumers to collect sensitive data from their users directly to Basis Theory's certified vault.
+The Basis Theory Android SDK makes it easy to build secure Android applications that
+[collect](/docs/concepts/elements#collect-sensitive-data) or [reveal](/docs/concepts/elements#reveal-sensitive-data)
+sensitive data using [Elements](/docs/concepts/elements).
 
-Think about it as an isolated sandbox within your mobile application that your end users are able to seamlessly
-interact with, and which securely communicates with the Basis Theory Vault. Sensitive data is not directly exposed to
-your application code, which keeps your mobile application out of compliance scope.
-
-Here's how we make this possible:
-
-- [Install](#installation) our Android SDK into your mobile application
-- Build forms using our **[Element](/docs/sdks/mobile/android/types)** input components
-- [Interact](/docs/sdks/mobile/android/services#basistheoryelements) with the Basis Theory API using **Element** references, not plaintext data
-- Own your UI/UX by fully customizing how **Elements** are [styled](/docs/sdks/mobile/android/options#styling)
-
-## Collect Sensitive Data
-
-Data entered by your end users into **Elements** is tokenized and secured within Basis Theory's certified Vault.
-
-Our SDKs provide several types of inputs to collect various types of data, such as the [CardNumberElement](/docs/sdks/mobile/android/types#cardnumberelement)
-for collecting credit card data and [TextElement](/docs/sdks/mobile/android/types#textelement) for collecting arbitrary textual data.
-
-Elements can be configured to support custom input masking, validation, and transformation rules to satisfy your use cases.
-
-## Reveal Sensitive Data
-
-Tokens stored within the Basis Theory Vault can be securely revealed to end users without accessing the plaintext
-data directly within your application code.
-
-<Alert>
-  The ability to reveal sensitive data on Android is not yet generally available. If you are interested in using this feature on Android,
-  please email us at <a href="mailto:info@basistheory.com?subject=Android SDK - Reveal">info@basistheory.com</a> to
-  join our early access program.
-</Alert>
+Get started with our [guide](/docs/guides/collect/collect-data-with-android), explore our
+[example application](https://github.com/Basis-Theory/basistheory-android/tree/master/example),
+or continue reading the [reference docs](/docs/sdks/mobile/android/types).
 
 ## Before You Begin
 
-Basis Theory Android Elements require the use of an API Key associated with a **Public Application**, which only allows `token:create` and `token:update` permissions to mitigate the risk that these API keys may be publicly exposed within your frontend applications.
+This SDK requires the use of an API Key associated with a **Public Application**, which only allows `token:create` or `token:update`
+permissions to mitigate the risk that these API keys may be publicly exposed within your frontend applications.
 
 To create one, login into our [Portal](https://portal.basistheory.com) and create a new "Public" Application with the permissions you require.
 

diff --git a/docs/sdks/mobile/ios/index.mdx b/docs/sdks/mobile/ios/index.mdx
@@ -18,42 +18,18 @@ import { SDK } from "@site/src/components/types";
 
 ###
 
-Basis Theory iOS Elements are simple, secure, developer-friendly inputs that empower consumers to collect sensitive data from their users directly to Basis Theory's certified vault.
+The Basis Theory iOS SDK makes it easy to build secure iOS applications that
+[collect](/docs/concepts/elements#collect-sensitive-data) or [reveal](/docs/concepts/elements#reveal-sensitive-data)
+sensitive data using [Elements](/docs/concepts/elements).
 
-Think about it as an isolated sandbox within your mobile application that your end users are able to seamlessly
-interact with, and which securely communicates with the Basis Theory Vault. Sensitive data is not directly exposed to
-your application code, which keeps your mobile application out of compliance scope.
-
-Here's how we make this possible:
-
-- [Install](#installation) our iOS SDK into your mobile application
-- Build forms using our **[Element](/docs/sdks/mobile/ios/types)** input components
-- [Interact](/docs/sdks/mobile/ios/services#tokenize) with the Basis Theory API using **Element** references, not plaintext data
-- Own your UI/UX by fully customizing how **Elements** are [styled](#styling-elements)
-
-## Collect Sensitive Data
-
-Data entered by your end users into **iOS Elements** is tokenized and secured within Basis Theory's certified Vault.
-
-Our SDKs provide several types of inputs to collect various types of data, such as the [TextElementUITextField](/docs/sdks/mobile/ios/types##text-element-ui-text-field)
-for collecting arbitrary textual data and [CardNumberUITextField](/docs/sdks/mobile/ios/types##card-number-ui-text-field) for collecting a credit card number.
-
-Elements can be configured to support custom input [masking](/docs/sdks/mobile/ios/options#mask), validation, and [transformation](/docs/sdks/mobile/ios/options#transform) rules to satisfy your use cases.
-
-## Reveal Sensitive Data
-
-Tokens stored within the Basis Theory Vault can be securely revealed to end users without accessing the plaintext
-data directly within your application code.
-
-<Alert>
-  The ability to reveal sensitive data on iOS is not yet generally available. If you are interested in using this feature on iOS,
-  please email us at <a href="mailto:info@basistheory.com?subject=iOS SDK - Reveal">info@basistheory.com</a> to
-  join our early access program.
-</Alert>
+Get started with our [guide](/docs/guides/collect/collect-data-with-ios), explore our
+[example application](https://github.com/Basis-Theory/basistheory-ios/tree/master/IntegrationTester),
+or continue reading the [reference docs](/docs/sdks/mobile/ios/types).
 
 ## Before You Begin
 
-Basis Theory iOS Elements require the use of an API Key associated with a **Public Application**, which only allows `token:create` and `token:update` permissions to mitigate the risk that these API keys may be publicly exposed within your frontend applications.
+This SDK requires the use of an API Key associated with a **Public Application**, which only allows `token:create` or `token:update`
+permissions to mitigate the risk that these API keys may be publicly exposed within your frontend applications.
 
 To create one, login into our [Portal](https://portal.basistheory.com) and create a new "Public" Application with the permissions you require.
 

diff --git a/docs/sdks/web/javascript/index.mdx b/docs/sdks/web/javascript/index.mdx
@@ -22,40 +22,18 @@ import { SDK } from "@site/src/components/types";
 
 ###
 
-**Basis Theory Elements** are secure inputs that empower developers to easily collect or reveal sensitive data within
-web or mobile applications.
+The Basis Theory JavaScript SDK makes it easy to build secure web applications that
+[collect](/docs/concepts/elements#collect-sensitive-data) or [reveal](/docs/concepts/elements#reveal-sensitive-data)
+sensitive data using [Elements](/docs/concepts/elements).
 
-Think about it as an isolated sandbox within your frontend application that your end users are able to seamlessly
-interact with, and which securely communicates with the Basis Theory Vault. Sensitive data is not directly exposed to
-your application code, which keeps your frontend systems out of compliance scope.
-
-Here's how we make this possible:
-
-- [Install](#installation) our JavaScript Elements SDK into your frontend application
-- Build forms using our **[Element](/docs/sdks/web/javascript/types)** input components
-- [Interact](/docs/sdks/web/javascript/methods#tokenization) with the Basis Theory API using **Element** references, not plaintext data
-- Own your UI/UX by fully customizing how **Elements** are [styled](/docs/sdks/web/javascript/options#style)
-
-### Collect Sensitive Data
-
-Data entered by your end users into **Elements** is tokenized and secured within Basis Theory's certified Vault.
-
-Our SDKs provide several types of inputs to collect various types of data, such as the [CardElement](/docs/sdks/web/javascript/types#card-element)
-for collecting credit card data and [TextElement](/docs/sdks/web/javascript/types#text-element) for collecting arbitrary textual data.
-
-Elements can be configured to support custom input masking, validation, and transformation rules to satisfy your use cases.
-
-### Reveal Sensitive Data
-
-Tokens stored within the Basis Theory Vault can be securely revealed to end users without accessing the plaintext
-data directly within your application code.
-
-Using one of our SDKs, sensitive data can be securely retrieved and applied to one or more Elements within your UI.
-See the section below on [detokenization](/docs/sdks/web/javascript/methods#detokenization) for more information.
+Get started with our [guide](/docs/guides/collect/collect-data-from-web), explore our
+[examples](https://github.com/Basis-Theory/basis-theory-js-examples),
+or continue reading the [reference docs](/docs/sdks/web/javascript/types).
 
 ## Before You Begin
 
-Basis Theory Elements require the use of an API Key associated with a **Public Application**, which only allows the use of `token:create` and `token:update` permissions, removing any risk that your API keys are stolen and used to access data.
+This SDK requires the use of an API Key associated with a **Public Application**, which only allows `token:create` or `token:update`
+permissions to mitigate the risk that these API keys may be publicly exposed within your frontend applications.
 
 To create one, login into our [Portal](https://portal.basistheory.com) and create a new "Public" Application with the permissions you require.
 

diff --git a/sidebars.js b/sidebars.js
@@ -168,6 +168,7 @@ const sidebars = {
         "concepts/access-controls",
         "concepts/what-is-the-proxy",
         "concepts/what-are-reactors",
+        "concepts/elements",
         "concepts/what-are-mats",
       ],
     },