Skip to main content
The Tako App Plugin allows your users to search and edit Tako knowledge cards via iframes to Tako’s UI. Anyone with a Tako API key will be able to utilize this plugin for a more integrated Tako experience within their own app. There are two Tako experiences you can integrate into your app:
  • A search page that displays a grid of Tako knowledge cards based on a text query. You can either send the queries manually or rely on a built-in search bar.
  • An edit page for customizing a Tako knowledge card (by modifying details like card title and series color).
See the bottom of this page for demo videos that show what each page looks like and how to integrate them into your app.

​
Rendering the Plugin

The Tako plugin will be rendered by your app via iframes to different Tako URLs. For example: 
<iframe
  id="takoSearch"
  src="https://trytako.com/plugin/search/"
  style="width:100%; height:400px;"
></iframe>
This renders the Search page with some styling to set the size of the iframe. You can size and layout the iframe element however you want to best fit your experience. The available plugin URLs are: 
https://trytako.com/plugin/search/
https://trytako.com/plugin/edit/?card_id=<card_id>&title=<card_title>
The search page will return edit page URLs to you for all cards that are editable, so you will not need to construct those URLs yourself. NOTE: Not all Tako cards are editable (yet). If a card is not editable, the edit button will not appear on that card in search results, and the plugin will not return an edit page URL for that card.

​
Authenticating the Plugin

Every time you load open a Tako iframe, you will need to authenticate the iframe with your API key. See the INIT_TAKO message documentation for more information.

​
Communicating with the Plugin

Your app will communicate with Tako iframes (and vice versa) through postMessage calls. This is how the app and the plugin iframes will tell each other which actions to take and with what payload (search queries, knowledge card URLs, etc.). You will both send messages to the plugin and listen for messages from the plugin. These are the available message types: 
enum PluginMessageTypes {
  // Events sent from your app to the plugin:
  INIT_TAKO = 'INIT_TAKO',
  SEARCH_TAKO = 'SEARCH_TAKO',
  
  // Events sent from the plugin to your app:
  SELECT_TAKO_RESULT = 'SELECT_TAKO_RESULT',
  OPEN_TAKO_EDITOR = 'OPEN_TAKO_EDITOR',
  CLOSE_TAKO_EDITOR = 'CLOSE_TAKO_EDITOR',
}

​
INIT_TAKO

Initializes the Tako iframe with your API credentials and any configuration options. Since each iframe functions independently of others, your app needs to call this on every iframe load to authenticate and call Tako endpoints. Payload: 
payload: {
  // Your Tako API key. Can be found at https://trytako.com/dashboard/
  apiKey: string;
  // When false, hides the edit buttons on all search results.
  // Defaults to true.
  hasEdit?: boolean;
  // When true, displays a search bar in the plugin iframe. Useful when you
  // don't want to build your own search bar or send SEARCH_TAKO messages.
  // Defaults to false.
  hasSearchBar?: boolean;
}
Usage: 
<iframe
  id="takoSearch"
  src="https://trytako.com/plugin/search/"
  style="width:100%; height:400px;"
></iframe>

<script>
  // Get the iframe element from the document using its id
  const iframe = document.getElementById('takoSearch');
  
  // Store your Tako API key as a secret. 
  // You can find your API Key at https://trytako.com/dashboard/
  const apiKey = TAKO_API_KEY;
  
  // When the iframe finishes loading, initialize it with your API key
  iframe.addEventListener('load', () => {
    iframe.contentWindow.postMessage(
      {
        type: 'INIT_TAKO',
        payload: { apiKey }
      },
      'https://trytako.com'
    );
  });
</script>

​
SEARCH_TAKO

Triggers a search for Tako knowledge cards. Call this whenever you want to find and display Tako cards. If you included hasSearchBar in your INIT_TAKO call, sending this message is likely unnecessary since the plugin’s built-in search bar will handle searching instead. Payload: 
payload: {
  // Query string that either includes long-form content for 
  // finding related knowledge cards or a short query for 
  // finding more targeted data
  query: string;
}
Usage: 
<iframe
  id="takoSearch"
  src="https://trytako.com/plugin/search/"
  style="width:100%; height:400px;"
></iframe>

<script>
  // Get the iframe element from the document using its id
  const iframe = document.getElementById('takoSearch');
  
  const query = "document text or user-entered query";
  
  const onSearch = () => {
    // Post a message to the iframe's contentWindow with a `payload` 
    // that includes the `query`
    iframe.contentWindow.postMessage(
      {
        type: 'SEARCH_TAKO',
        payload: { query }
      },
      'https://trytako.com'
    );
   }
  
   // Call this whenever you want to trigger a new Tako search
   onSearch();
</script>

​
SELECT_TAKO_RESULT

Sent to your app from the Tako plugin whenever a user selects a Tako result, either by clicking on a card in the Tako search results or by selecting “Insert Card” in the Tako editor. You should listen for this event in your app and handle the payload as needed. Payload: 
payload: {
  // The URL of the selected Tako card embed. You can render
  // this in an iframe in your document to display the card 
  cardUrl: string;
  // The Tako editor URL for the selected Tako card.
  // You can use this to open the Tako editor in a separate iframe.
  //
  // NOTE: Not all Tako cards are editable (yet). If a card is not 
  // editable, the edit button will not appear and the editorUrl will
  // not be returned here.
  editorUrl: string;
}
Usage: 
window.addEventListener('message', event => {
  if (event.origin !== 'https://trytako.com') return;
  if (event.data.type === 'SELECT_TAKO_RESULT') {
    const { cardUrl, editorUrl } = event.data.payload;
    
    // Do what you want with the cardUrl and editorUrl
    //
    // ex: Display the cardUrl in an iframe, save the 
    // editorUrl so you can show the Tako editor when 
    // the user clicks your own Edit button, etc...
  }
});

​
OPEN_TAKO_EDITOR

Sent to your app from the Tako plugin whenever a user clicks the Edit button on a Tako search result. If a Tako card is editable and you have not disabled editing via the hasEdit param in INIT_TAKO, an edit button will appear in the top right corner of the search result on hover. You should listen for this event in your app and handle the payload as needed. Payload: 
payload: {
  // The URL of the selected Tako card embed. You can render 
  // this in an iframe in your document to display the card 
  cardUrl: string;
  // The Tako editor URL for the selected Tako card. You can 
  // use this toopen the Tako editor in a separate iframe
  editorUrl: string;
}
Usage: 
window.addEventListener('message', event => {
  if (event.origin !== 'https://trytako.com') return;
  if (event.data.type === 'OPEN_TAKO_EDITOR') {
    const { cardUrl, editorUrl } = event.data.payload;
  
    // ex: render the editorUrl in a larger iframe on your page
  }
});

​
CLOSE_TAKO_EDITOR

Sent to your app from the Tako plugin whenever a user clicks the Cancel button in the Tako editor You should listen for this event in your app. Payload: 
payload: {}
Usage: 
window.addEventListener('message', event => {
  if (event.origin !== 'https://trytako.com') return;
  if (event.data.type === 'CLOSE_TAKO_EDITOR') {    
    // ex: hide the Tako editor iframe
  }
});

​
Theming the Plugin

​
Dark Mode

You can force dark or light mode on any plugin page (or Tako knowledge card) by appending ?dark_mode=true or ?dark_mode=false to the src URL. For example, https://trytako.com/plugin/search/?dark_mode=true yields a search experience like this: Dark mode search and https://trytako.com/plugin/search/?dark_mode=false yields a search experience like this: Light mode search

​
Demo Videos

Search
Edit
⌘I