Extension SDK API referenceBeta
UI extensions have access to context props and utility functions that let them interact with an app’s users and the Stripe Dashboard ecosystem. This page documents these values and functions.
Props
Views are passed props that the extension can use for context on where the extension is being displayed. Your view can take some or all of these props as arguments, and they’re of type ExtensionContextValue
.
import type {ExtensionContextValue} from '@stripe/ui-extension-sdk/context'; const ExampleApp = ({userContext, environment, oauthContext}: ExtensionContextValue) => { ... }
User context
The userContext
prop has data about the end user using your app, including these fields:
Field | Type | Example |
name | string | Jenny Rosen |
The app user’s name | ||
account.country | string | UK |
The app user’s country | ||
account.id | string | acct_1032D82eZvKYlo2C |
The app user’s account ID | ||
account.name | string | Jenny’s Llama Emporium |
The name of the Stripe account | ||
locale | string | en-GB |
The app user’s system language ID |
Environment
The environment
prop has data about the page a user is viewing, including these fields:
Field | Type | Example |
viewportID | string | stripe.dashboard.payment.list |
Current viewport rendering your view | ||
mode | ‘live’ | ‘test’ | live |
The Stripe API mode the current page is in | ||
objectContext.id | string | ch_3L0pjB2eZvKYlo2C1u1vZ7aK |
In the ObjectView objects, this is the ID of the current object the user views in the Dashboard. | ||
objectContext.object | string | charge |
In the ObjectView objects, this is the type of the current object the user views in the Dashboard. | ||
constants | Object | {"API_BASE": "https://api.example.com/v1"} |
An object with arbitrary constant values passed from the app manifest that can be overridden for local development using the CLI manifest flag. |
OAuth context
The oauthContext
prop contains information about the current OAuth workflow, if one is underway.
Field | Type | Example |
error | string | none |
OAuth error code | ||
code | string | none |
OAuth authorization code | ||
state | string | none |
OAuth state used by your app | ||
verifier | string | none |
OAuth code verifier |
Utility functions
The UI extension SDK provides these functions to help apps interact with the Stripe API and the Dashboard user.
- clipboardWriteText—Write text to the end user’s clipboard.
- createOAuthState—Obtain values to use when you create an authorization link in an OAuth workflow.
- fetchStripeSignature—Get a signature from Stripe’s servers.
- getDashboardUserEmail—Get the end user’s email address.
- showToast—Show a toast message to the user.
- useRefreshDashboardData—Enable your view to update data on the Dashboard.
clipboardWriteText
Write text to the app user’s clipboard. The user can then paste it as if they had copied it.
Argument | Type | Example |
text | string | Hello, world! |
Text to copy |
To use this function, first import it from the SDK:
import {clipboardWriteText} from '@stripe/ui-extension-sdk/utils';
For example, provide a button that copies Hello, world!
to the clipboard when pressed. In a real app, you could use this to copy an address, invoice number, or other important detail.
import {useCallback} from 'react'; import {Button} from '@stripe/ui-extension-sdk/ui'; import {clipboardWriteText} from '@stripe/ui-extension-sdk/utils'; const App = () => { const writeToClipboard = useCallback(async () => { try { await clipboardWriteText('Hello, world!'); // Writing to the clipboard succeeded } catch (e) { // Writing to the clipboard failed } }, []); return ( <Button onPress={writeToClipboard} > Copy to clipboard </Button> ); };
createOAuthState
Obtain state
and challenge
values to use when you create an authorization link in an OAuth workflow.
To use this function, first import it from the SDK.
import {createOAuthState} from '@stripe/ui-extension-sdk/utils';
For an example in context, see Add authorization workflows.
fetchStripeSignature
Get a signature from Stripe’s servers. Your UI extension can use this signature to send signed requests to your app’s backend.
To use this function, first import it from the SDK.
import {fetchStripeSignature} from '@stripe/ui-extension-sdk/utils';
For more details and an example in context, see server-side logic docs.
getDashboardUserEmail
Get the app user’s email address.
To use this function, first import it from the SDK.
import {getDashboardUserEmail} from '@stripe/ui-extension-sdk/utils';
You must also include the user_email_read
permission in your app manifest. Add it using a CLI command or edit the app manifest file directly.
For example, access the app user’s email in a view by getting it using the getDashboardUserEmail
function and storing it in a React state variable.
import {useEffect, useState} from 'react'; import {getDashboardUserEmail} from '@stripe/ui-extension-sdk/utils'; export const useDashboardUserEmail = () => { const [email, setEmail] = useState<string | null>(null); const fetchEmail = async () => { try { const {email} = await getDashboardUserEmail(); setEmail(email); } catch(e) { console.error(e); } }; useEffect(() => { fetchEmail(); }, []); return email; }; const App = () => { const dashboardUserEmail = useDashboardUserEmail(); ... };
showToast
Render a toast at the bottom of your view to inform the user about the status of an action. For example, a toast can show a user whether an API call succeeded or failed.
import {showToast} from '@stripe/ui-extension-sdk/utils'; const App = () => { const handleClick = () => { fetch(...) .then((response) => { showToast("Invoice updated", {type: "success"}) return response.json() }) .catch(() => { showToast("Invoice could not be updated", {type: "caution"}) }) } // Use the `handleClick`... }
The showToast()
function takes two arguments, a message
and options
. The function is defined as follows:
type ToastType = "success" | "caution" | "pending" | undefined; type ToastOptions = { type?: ToastType; action?: string; onAction: () => void; } (message: string, options?: ToastOptions) => Promise<{ update: (updateMessage: string, updateOptions?: ToastOptions) => void; dismiss: () => void; }>;
Toast messages can’t exceed 30 characters in length or be empty. If a message is too long or empty, the console logs an error.
Unless they’re of type pending
, toasts dismiss automatically.
Is Pending | Has Action | Timeout |
---|---|---|
false | false | 4s |
false | true | 6s |
true | false | None |
true | true | None |
import {showToast} from '@stripe/ui-extension-sdk/utils'; const App = () => { const handleClick = async () => { const { dismiss, update } = await showToast("Refreshing data", { type: "pending", }); try { await refreshData(); dismiss(); } catch (error) { update("Data could not be refreshed", { type: "caution" }); } } // Use the `handleClick`... }
Toasts can also prompt the user to take an action. Clicking the action button automatically dismisses the toast.
import {showToast} from '@stripe/ui-extension-sdk/utils'; const App = () => { const handleClick = async () => { let timeout; const { dismiss } = await showToast('Message "sent"', { action: "Undo", onAction: () => { clearTimeout(timeout); showToast('Message "unsent"'); }, }); timeout = setTimeout(() => { sendMessage(); dismiss(); }, 3000); } // Use the `handleClick`... }
useRefreshDashboardData
Enable your view to update data in the Dashboard. This function returns another callback function. Store that callback, and call it when Stripe data changes. When you call it, the Dashboard updates to reflect the new values.
To use this function, first import it from the SDK.
import {useRefreshDashboardData} from '@stripe/ui-extension-sdk/utils';
For instance, on a customer detail page, get the callback function that refreshes Dashboard data, and then call it after updating the current customer.
import {useCallback} from 'react'; import {useRefreshDashboardData} from '@stripe/ui-extension-sdk/utils'; const App = () => { const refreshDashboardData = useRefreshDashboardData(); const updateCustomer = useCallback(async () => { try { await updateCurrentCustomer(); await refreshDashboardData(); } catch (error) {} }, [refreshDashboardData]); }
For more information, view docs on accessing Stripe objects in the Dashboard.