Embedding Retool and Public Apps
This probably won't work on non-HTTPS websites!
Our authentication scheme requires Secure Cookies which only work in an HTTPS environment. Most modern browsers will not allow the inner iFrame to access these cookies, and the embedded Retool will auto-logout.
You can embed Retool via our SDK, share your app publicly through an iFrame, or use our pre-built React wrapper.
Embedding Retool
Quick start: vanilla JavaScript
Include the Retool SDK and then initialize the dashboard using the following JavaScript call.
<script src="https://cdn.tryretool.com/embed.js"> </script>
...
<div id="container" style="height:100vh; width:100vw" />
<script>
var rt = window.retool.RetoolDashboard(document.getElementById('container'), 'http://yourco.retool.com/editor/test_embeds')
</script>
Quick start: React
Install the react-retool npm module and import into your project.
// with npm
$ npm install react-retool --save
// with yarn
$ yarn add react-retool
import Retool from "react-retool";
function App() {
return (
<Retool url="https://retoolin.tryretool.com/embedded/public/f7607e1f-670a-4ebf-9a09-be54cf17181e" />
);
}
export default App;
Visit the README on npm for detailed documentation about the React wrapper (link).
Example: vanilla JavaScript
Here's a quick and simple example to get a feel for how to embed Retool in other web applications.
First, create a new HTML file and copy paste the below snippet in. Make sure to replace the placeholder URL with your actual Retool domain.
<html>
<head>
<script src="https://cdn.tryretool.com/embed.js"> </script>
<script>
function incrementCompanyId () {
var d = document.getElementById('companyid');
var curValue = parseInt(d.textContent)
d.textContent = String(curValue + 1)
}
</script>
</head>
<body>
<h1> Company id</h1>
<p id="companyid">13</p>
<button onclick="incrementCompanyId()"> increment me </button>
<h1> User id</h1><p>1433</p>
<div style="height: 800px; width: 100%;" id='container'></div>
<script>
var rt = window.retool.RetoolDashboard(document.getElementById('container'), 'https://retool.yoursite.com/apps/embedded-app')
</script>
</body>
</html>
Next, try pulling in some information from the host page like this:
We used the "Parent Window Query" and supplied the CSS selector for the company id in our host page (#companyid). Then we created a text component, and rendered that value using {{ query1.data }}.
If you press on the "Increment me" button - you'll see that Retool automatically picks up the changes from the host page.
Example: React
Here's a similar example to the one above, but using React.
import React from "react";
import Retool from "react-retool";
class App extends React.Component {
constructor(props) {
super(props);
this.state = { value: 0 };
}
buttonClicked(event) {
this.setState({ value: this.state.value + 1 });
}
render() {
return (
<div className="App">
<div className="parent-react-app-container">
<h1>I am a react app</h1>
<h2>
Value Retool will read on load:{" "}
<span id="id-value-retool-reads">hello</span>
</h2>
<div>
<h2>
<span id="other-id-value-retool-reads">{this.state.value}</span>
</h2>
<button onClick={this.buttonClicked}>
Increment Dynamic Value
</button>
</div>
</div>
<div className="retool-box">
<Retool url="https://retool.yoursite.com/apps/embedded-app" />
</div>
</div>
);
}
}
export default App;
This example also relies on a Retool app with Parent Window Queries reading the values from the parent page.
Sending Messages to the Parent Application
Embedded Retool applications can use Parent Window Queries to read values in from the parent application. What if you wanted to send a message in the other direction, from the embedded application to the parent application? You can use a Retool JavaScript query to accomplish this via the browser's postMessage API.
For example, if we wanted to send the current_user's email address to the parent application, it might look like this:
parent.postMessage(current_user.email, 'https://retool.yoursite.com/apps/embedded-app')
There are different ways the parent application can listen to and handle events. The specific implementation will vary, but for illustrative purposes here is a simple example of code that the parent application could include:
window.addEventListener('message', function(e) {
console.log('Parent window received: ', e.data);
}, false);
Tip: Hiding the Retool nav bar
You can hide the Retool navigation bar using the
_hideNav=truequery parameter. Similarly, you can hide the query timer using_hideTimer=true.
User Authentication in Embedded Apps
It is often the case that you have an existing admin tool that you're embedding Retool apps inside of. This is a nice way to keep the process of switching to Retool simple for end-users, as they can continue to access the tool they're familiar with while allowing developers to build net-new functionality in Retool. Managing authentication between the parent application and the embedded Retool applications can be challenging. This section describes some common patterns to address these challenges.
Can I pass the authentication state from my parent application into Retool?
This is a common question. In short, no. However, in many circumstances, things can be set up to provide very similar behavior as if we were able to directly pass authentication state between the two applications.
User Authentication in Embedded Public Apps
Public Retool apps don't require authentication. If you're embedding a public Retool app into your existing web application, you don't need to do anything to handle the user's state, because there is no user signed into Retool.
User Authentication with SAML/OIDC SSO
Setting up SAML or OIDC SSO is the best way to handle authentication of embedded Retool apps. As long as your existing web application uses the same SSO Identity Provider (IDP) as Retool, the user's authentication state can easily be shared between the two.
Avoiding Double-login
If you configure your web application and Retool to use the same SSO IDP, a user might SSO into the web application, then have to SSO into the embedded Retool application. Although this will work, it is an undesirable and confusing flow for the user. Rather than prompting a login screen, you can set up Retool to automatically try to sign the user in with SSO. This will work if the user has an existing, authenticated session on the IDP — we know they will because they're signed into that parent application.
To configure this, set the TRIGGER_SAML_LOGIN_AUTOMATICALLY, or TRIGGER_OAUTH_2_SSO_LOGIN_AUTOMATICALLY (depending on if you're using SAML or OIDC SSO) environment variable to true in your docker.env file.
Public Apps
You can share your Retool app publicly via a public link, and embed it in an iFrame in other applications or web pages. To get started, head over to the app you want to share, and make sure you're in edit mode. Click the "Share" button on the top right of your screen, and select the "Public" tab. You should see a link that you can quickly copy and share.
Public apps and Retool plans
Public apps are only available on the Business and Enterprise plans.
Here's an example of an embedded public Retool app from our Working with select components tutorial, via an iFrame:
You can add optional password protection to your public apps, too.
The authentication scheme here isn't rock solid though, so don't put sensitive data behind a password protected public Retool app.
On-premise Setup
If you're looking to embed a Retool app that's hosted via an on-premise Retool instance, please double check your environment variables. The COOKIE_INSECURE environment variable must be set to false.
Updated 10 days ago