Working with UX Toolkit within Native Webviews

Instructions on how to use UX Toolkit web components and two-way communication to configure and interact with webviews. Marqeta’s UX Toolkit web components use iframes to ensure customer web applications maintain PCI compliance, without requiring customers to be compliant themselves. The iframes at the core of UX Toolkit web components simplify using UX Toolkit web components in native webviews. You can use the UX Toolkit iframe HTML file URL—UXT_WEBVIEW_SRC—as the source for all webviews and leverage two-way communication via postMessage() to configure and interact with them.

Note
You can display multiple UX Toolkit components on a single screen by rendering a webview for each component. To manage this webview logic, you may opt to create a new component within your application platform, making it simpler to repeat without interfering with other webviews.

Important
This version of UX Toolkit supports only prepaid and debit card programs in the United States.

Authentication

To authenticate webviews, follow the authentication flow as described in Customer Authentication API. For webviews specifically, you must use the apiHeadersResolver property to pass required authentication bearer tokens or session tokens generated from your platform for your application. To see an example of how to pass apiHeadersResolver, see the code example in About the window.postMessage() method.

Note
You must configure Cross-Origin Resource Sharing (CORS) on your authentication endpoint to allow POST and OPTIONS requests from https://web.ux-toolkit.marqeta.com. Webview implementations fail without this configuration.

Sending post messages

When initiating your webview and UX Toolkit component, a window.postMessage() JavaScript call needs to be injected into the webview.

About post messages

JavaScript and Document Object Model (DOM) Storage must be enabled in order to use UX Toolkit components within webviews. Be aware that webview content size may change. For details, see Capturing resize events.

About the window.postMessage() method

The message property of the window.postMessage() method must be setProps. The globalProps property contains:

Field	Description
`authParams`	This object contains the following elements: - `apiEndpoint` (Required): The string value of a fully-qualified URL representing your authentication API endpoint. - `apiHeadersResolver` (Optional): This object is used to pass any session or auth token headers to your authentication API endpoint for the purpose of authenticating users with your application.
`componentName`	The string value of any component available to your program, as listed in Studio. Component names must be in kebab case.
`envName`	(Optional) Indicates which environment is being targeted. Allowable values for this field are `sandbox` or `production`. The default value for this field is `production`.
`postMessageAgentName`	The string value for the `postMessage()` agent name. For details, see Receiving post messages.
`themeName`	(Optional) The name of an existing theme that was created using the `/theme` endpoint. The default value of this field is `default`. For more information on the `/theme` endpoint, see Themes section on the Customizing UX Toolkit page.

The componentProps property contains the necessary properties and attributes for the component, as listed in Studio. All kebab-case HTML component properties (e.g., kebab-case-property) must be converted to lower camelCase (e.g., lowerCamelCase) when passed to componentProps. The final argument to window.postMessage() must be the valid base URL. If the base URL does not match the webview source hostname, the call to window.postMessage() will fail. The following example uses React Native:

JavaScript

const UXT_CDN_BASE_URL = 'https://web.ux-toolkit.marqeta.com';
const SHORT_CODE = 'YOUR_PROGRAM_SHORT_CODE';
const UXT_WEBVIEW_SRC = `${UXT_CDN_BASE_URL}/${SHORT_CODE}/releases/1/www/iframe-page-root/index.html`;
let webview1: WebView | null = null;
return (
  <WebView
    ref={(ref) => (webview1 = ref)}
    originWhitelist={['*']}
    source={{ uri: UXT_WEBVIEW_SRC }}
    javaScriptEnabled={true}
    domStorageEnabled={true}
    showsVerticalScrollIndicator={false}
    style={{ height: '240px' }}
    onLoadEnd={() => {
      webview1?.injectJavaScript(`
        window.postMessage(
          {
            message: 'setProps',
            globalProps: {
              authParams: {
                apiEndpoint: 'https://your-domain/api/auth',
                apiHeadersResolver: {
                  'Authorization': 'Bearer SOME-AUTH-TOKEN-HERE'
                  }
              },
              envName: 'sandbox',
              themeName: 'your-theme-name-here',
              componentName: 'mq-card',
              postMessageAgentName: 'ReactNativeWebView',
            },
            componentProps: {
              cardToken: 'fd076080-0568-409d-8fc0-af1159a1826d',
              canChangeSides: true,
            },
          },
          '${UXT_CDN_BASE_URL}',
        );
      `);
    }}
  />
);

Receiving post messages

Receiving messages from inside the webview is similar to sending them. However, there are differences across the native platforms, React Native, iOS, Android, and Flutter. Every platform contains a post message agent or object with a postMessage(message: string): void method called by the UX Toolkit component. This is the method by which the events listed in Studio are passed to your native application. Each platform has a predefined convention for the locations of the postMessage() methods. The string value passed to postMessage() is a string-encoded JSON object. You can seamlessly integrate behaviors between two UX Toolkit components and webviews. For example, if you have the mq-card and mq-card-actions on the same screen, you can listen for the respective message on the mq-card-actions component when a card is locked, and you can then refresh the mq-card webview to reflect the new changes. When you refresh a webview, you must repost the initialization message as described in Sending post messages. For React Native, iOS, Android, and Flutter platforms, the agent/object is referenced within JavaScript’s window object. However, the name of the agent/object varies. Use the postMessageAgentName property to specify the location of the agent/object as follows:

Platform	Agent/Object	`postMessageAgentName`
React Native	`window.ReactNativeWebView.postMessage()`	`ReactNativeWebView`
iOS	`window.webkit.messageHandlers.YOUR_HANDLER_NAME.postMessage()`	`webkit.messageHandlers.YOUR_HANDLER_NAME`
Android	`window.YOUR_HANDLER_NAME.postMessage()`	`YOUR_HANDLER_NAME`
Flutter	`window.YOUR_HANDLER_NAME.postMessage()`	`YOUR_HANDLER_NAME`

The following example uses React Native:

JavaScript

const UXT_CDN_BASE_URL = 'https://web.ux-toolkit.marqeta.com';
const UXT_WEBVIEW_SRC = `${UXT_CDN_BASE_URL}/VALID_PROGRAM_SHORT_CODE/releases/1/www/iframe-page-root/index.html`;

let webview1: WebView | null = null;

return (
  <WebView
    ref={(ref) => (webview1 = ref)}
    originWhitelist={['*']}
    source={{ uri: UXT_WEBVIEW_SRC }}
    // ... other props
    onMessage={(event) => {
      // The event data is a JSON string and needs to be parsed
      const data = JSON.parse(event.nativeEvent.data);
      console.log('Received from WebView1:', data);
    }}
  />
);

Capturing resize events

Webviews and UX Toolkit web components are generally responsive by default to viewport changes such as orientation adjustments. However, there are scenarios where the contents of the webview may grow or shrink in height, and the webview is not likely to self-adjust accordingly. In such cases, an event message is triggered when the height of the content changes, giving you the opportunity to adjust the height of the webview. The following example uses React Native:

JavaScript

const UXT_CDN_BASE_URL = 'https://web.ux-toolkit.marqeta.com';
const UXT_WEBVIEW_SRC = `${UXT_CDN_BASE_URL}/VALID_PROGRAM_SHORT_CODE/releases/1/www/iframe-page-root/index.html`;

let webview1: WebView | null = null;
const [webview1Height, setWebview1Height] = useState(240);

return (
  <WebView
    ref={(ref) => (webview1 = ref)}
    originWhitelist={['*']}
    source={{ uri: UXT_WEBVIEW_SRC }}
    style={{ height: webview1Height }}
    // ... other props
    onMessage={(event) => {
      const data = JSON.parse(event.nativeEvent.data);
      const { eventName, height } = data;

      if (eventName === 'iframeBodyResize') {
        setWebview1Height(height);
      }
    }}
  />
);

Guides

Integrating with Native Webviews

Authentication

Sending post messages

About post messages

About the window.postMessage() method

Receiving post messages

Capturing resize events

​Authentication

​Sending post messages

​About post messages

​About the window.postMessage() method

​Receiving post messages

​Capturing resize events

Authentication

Sending post messages

About post messages

About the window.postMessage() method

Receiving post messages

Capturing resize events