Working with UX Toolkit within Native Webviews

Marqeta’s UX Toolkit web components use iframes to ensure customers’ 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 prepaid and debit card programs in the United States, Canada, and the EU.

Authentication

To authenticate webviews, follow the authentication flow as described in UX Toolkit Getting Started. However, for webviews, 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 the About the window.postMessage() method section below.

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. Key considerations for sending post messages from your native application to the UX Toolkit component inside the webview are outlined in the following section.

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’s 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. For more information about authentication, see Authentication workflow. - `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 provided 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 Upload theme object.

The componentProps property contains the necessary properties and attributes for the component, as listed in Studio. All kebab case HTML component properties, such as kebab-case-property, must be converted to lower camel case (e.g., lowerCamelCase) when passed to componentProps. The final argument in the 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. Note that the string value which is 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	Post Message Agent Name	Post Message Resource
React-Native	`window.ReactNativeWebView.postMessage()`	`ReactNativeWebView`	React-Native implementation
iOS	`window.webkit.messageHandlers.YOUR_HANDLER_NAME.postMessage()`	`webkit.messageHandlers.YOUR_HANDLER_NAME`	iOS implementation
Android	`window.YOUR_HANDLER_NAME.postMessage()`	`YOUR_HANDLER_NAME`	Android implementation
Flutter	`window.YOUR_HANDLER_NAME.postMessage()`	`YOUR_HANDLER_NAME`	Flutter implementation

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 }}
    ... // truncated props for longevity sake
    onMessage={(event) => {
      // remember: the event data is passed as 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. “Viewport” refers to the part of the screen that is being viewed. 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 }}
    ... // truncated props for longevity sake
    onMessage={(event) => {
      const data = JSON.parse(event.nativeEvent.data);
      const { eventName, height } = data;

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

​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