OpenPass SDK for JavaScript overview
To facilitate the integration of OpenPass with your website, use the OpenPass SDK for JavaScript. This SDK offers several options for optimizing the user experience, including:
- Three different ways to sign in: using a customizable Sign In with OpenPass button, filling out an inline sign-in form, or using your own sign-in button.
- Different flows for the sign-in and authentication process.
With this SDK, you can use OpenPass fully from the client side. There is no requirement for server-side interaction.
To allow users to experience some of the benefits of OpenPass before verifying their accounts, implement Delayed verification.
For details on integrating your OpenPass implementation with UID2, contact your Technical Account Manager at The Trade Desk.
Minimum requirements
JavaScript ES6
Integration options
To optimize the user experience and make integrating OpenPass with your site or app easier, the SDK offers different options. Choose one of them to access a quickstart guide with detailed installation instructions.
| Option | Description | Examples |
|---|---|---|
| "Sign In with OpenPass" button | Renders a sign-in button with a custom shape, size, additional width spacing, text option, and theme. | |
| Co-branding: Inline sign-in form | Renders the sign-in form directly within a web page using an iframe for a more seamless and integrated user experience. It also offers a better branding experience by placing the publisher's logo and display name at the top of the sign-in form, not next to the OpenPass brand. Includes the dark mode option. | |
| QuickAuth | Render a QuickAuth sign-in popup directly within a web page or app. QuickAuth verifies the user's identity using only their email address. After the email address is verified, the user can quickly sign in to other QuickAuth-enabled websites and apps with a single click or tap, eliminating the need to remember and enter login credentials. | |
| Custom sign-in button (add a click handler) | It is recommended by The Trade Desk that you use one of the previous options in this table because they are more secure and user-friendly. However, as an option, you can manually add the click handler yourself. | N/A |
Authentication flow
This SDK enables users to use SSO for authenticating their identity on your site or app. To get started, choose a flow for what happens after sign-in.
| Flow | Description | Notes |
|---|---|---|
| Redirect | The browser or app redirects the entire page to the OpenPass Universal Login sign-in form, and then back to your site when the user has completed the sign-in. | This option is easier to implement than the popup flow. It's also more secure because you can check the redirect URL in the browser's address bar to ensure you are in the same domain. |
| Popup | The browser or app opens an OpenPass sign-in popup window separate from the originating page. When the sign-in is complete, the popup closes and a message is sent back to your site notifying that the user has signed in. | This option is recommended for single-page applications (SPAs) or sites where navigating from the current page and reloading is not optimal. |
NOTE: As an option, the popup flow can fall back to a full-page redirect sign-in if the popup cannot be created.
Redirect flow
This flow does a full-page redirect to the OpenPass Universal Login sign-in form. On successful authentication, OpenPass redirects the user back to your site, where you must complete the authentication flow.
NOTE: This flow can be used as the fallback if the popup flow cannot create a popup window.
The following is a screenshot of the OpenPass Universal Login page.
Popup flow
This flow opens the OpenPass sign-in form in a popup window separate from your site or app. This allows the user to continue seeing your organization's page to preserve the user's flow. Popups work well with single-page applications (SPAs) or sites where navigating away from the current page is not optimal.
NOTE: If it's not possible to create a popup window, OpenPass can fall back to a full-page redirect sign-in. This can happen if the popup is blocked.
The following is a screenshot of the sign-in popup window.
Handle authentication failure
In most cases, the authentication is successful, but there are some where they are not. For example, there might be an invalid redirect_uri parameter, an incorrect client ID value, or a connectivity issue.
Here's what you need to know:
- OpenPass user errors (such as entering the wrong one-time validation code) are displayed on the OpenPass sign-in form.
- If a valid value is provided for the
redirect_uriparameter and there is an error on the OpenPass sign-in form that terminates sign-in, the user is redirected to the specified URI. The redirect includes error details on the query string (error code, error description, and an error URL). - If an invalid
redirect_uriparameter is provided, any sign-in terminating errors that occur in the OpenPass sign-in form are displayed on the OpenPass site.
The following screenshot shows an error page on the OpenPass site.
For more information, see Redirect URIs.
Delayed verification
To allow users to experience some of the benefits of OpenPass before verifying their accounts, implement Delayed verification. This feature enables you to offer exclusive content for both unverified and verified users. Verified users can then access more exclusive content by both entering and confirming their email address.
Documentation
The following list of JavaScript SDK documentation includes the quickstart and API reference guides.
Quickstart Guides:
- Customizable "Sign In with OpenPass" button
- Co-branding: Inline sign-in form
- QuickAuth sign-in form
- Custom sign-in button (add a click handler)
- Sign-in for web TV
Other documentation:
- Reference guide
- Release notes
- Sample Site Implementations
To make the user experience consistent and enjoyable, we provide OpenPass Integration best practices and co-branding guidelines. The latter includes a ZIP file with SVG logos and other web assets.