Advanced Topics

UI Customization

This section goes into more detail regarding the parts of the Quick Start HTML snippet and how you can further customize each part.

Defining the form

By default, the snippet assumes that the web backend endpoint for processing the submitted form is located at the same URL as the page displaying Pinn JS Widget. If your endpoint is located at another URL, specify an action attribute for your form. For example,

<form action="/pinn_verification" method="post" id="pinn_form"></form>

You can also add any input tags inside the form that may be helpful to your backend for processing. Just remember that any data contained therein are not secure unless you check them for forgery.

Customizing the page

The Pinn Widget only requires a portion of the web page to render and function properly. You are free to style the surrounding parts of the page for branding and for consistency with the rest of your web application.

Sizing the iframe

By default, the above snippet lets the Widget render over the entire page. If, however, you would like to customize the styling around the widget, you can constrain the size of the iframe to fit a containing div. But set a minimum size sufficient for the widget to render well on small screens, including when displaying a QR code. For example,

        #pinn_iframe {
            width: 100%;
            height: 100%;
            min-width: 320px;
            min-height: 480px;
            border: none;

<div class="my-container">
    <iframe id="pinn_iframe"></iframe>

Remember to test the layouts with a variety of screen sizes.

Rendering on mobile screens

Because the Pinn login widget is optimized to render well on all screen sizes, you should include the following meta tag in the head of your page:

  <meta name="viewport" content="width=device-width, initial-scale=1" />

Handling Errors

The Widget is designed for simple error handling by default. With no additional code, the system will behave reasonably. This section discusses additional options.

The use of the Widget can generate a number of possible errors that include configuration errors, user authentication errors, network errors, and backend API errors. The Widget is designed to handle most errors internally with the following exceptions:

  • Configuration error: if the JS SDK is not configured properly, an error page will be displayed to the user and details will be shown in the JavaScript console. An example would be if the submitted publishable key is no longer valid.
  • Authentication error: if the user fails to authenticate with Pinn, the form on the page will be submitted with an invalid id_token. Your backend code should already handle this scenario, as described in the authentication section.



We are here to help! Contact us with any development related questions at dev@pinn.ai and we'll reach back in a timely manner.