Franz Recipes – Getting Started

A Franz recipe is basically nothing else than a node module. You can access all of the electron modules as well.

Installation

1. To install a new integration, download the integration folder e.g whatsapp.
2. Open the Franz Plugins folder on your machine (note that this dev directory may not exist yet, and you must create it):
   • Mac: ~/Library/Application Support/Franz/recipes/dev/
   • Windows: %appdata%/Franz/recipes/dev/
   • Linux: ~/.config/Franz/recipes/dev
3. Copy the whatsapp folder into the plugins directory
4. Reload Franz

Recipe structure

Every recipe needs a specific file structure in order to be detected as a Franz recipe

• recipes/dev/[NAME]/
• icon.svg
• icon.png
• index.js
• package.json
• webview.js
• darkmode.css

Configuration: package.json

The package.json is structured like any other node module and allows to completely configure the service.

{
  "id": "tweetdeck",
  "name": "Tweetdeck",
  "version": "1.0.1",
  "description": "Tweetdeck",
  "main": "index.js",
  "author": "Stefan Malzner <[email protected]>",
  "license": "MIT",
  "repository": "https://github.com/meetfranz/recipe-tweetdeck",
  "config": {
    "serviceURL": "https://tweetdeck.twitter.com/"
  }
}

To get more information about all the provided configuration flags, check the config docs.

Backend: index.js

This is your "backend" code. Right now the options are very limited and most of the services don't need custom handling. If a service is relatively straight forward and has a static URL likei messenger.com, [TEAMID].slack.com or web.skype.com all you need to do to return the Franz Class:

// default integration (e.g messenger.com, ...)
module.exports = Franz => Franz;

If your service can be hosted on custom servers, you can validate the given URL to detect if it's your server and not e.g. google.com. To enable validation you can override the function validateServer

// RocketChat integration
module.exports = Franz => class RocketChat extends Franz {
  async validateUrl(url) {
    try {
      const resp = await window.fetch(`${url}/api/info`, {
        method: 'GET',
        headers: {
          'Content-Type': 'application/json',
        },
      });
      const data = await resp.json();

      return Object.hasOwnProperty.call(data, 'version');
    } catch (err) {
      console.error(err);
    }

    return false;
  }
};

validateServer needs to return a Promise, otherwise validation will fail.

Frontend: webview.js

The webview.js is the actual script that will be loaded into the webview. Here you can do whatever you want to do in order perfectly integrate the service into Franz. For convenience, we have provided a very simple set of functions to set unread message badges (Franz.setBadge()) and inject CSS files (Franz.injectCSS()).

// orat.io integration
module.exports = (Franz) => {
  function getMessages() {
    let direct = 0;
    let indirect = 0;
    const FranzData = document.querySelector('#FranzMessages').dataset;
    if (FranzData) {
      direct = FranzData.direct;
      indirect = FranzData.indirect;
    }

    Franz.setBadge(direct, indirect);
  }

  Franz.loop(getMessages);
}

To get more information about the provided functions, check the Frontend API docs.

General Information

Icons

In order to show every service icon crystal clear within the Franz UI, we require a .svg and .png in 1024x1024px.

Dark Mode

You can provide a custom Dark Mode Theme for your recipes just by putting the darkmode.css into your recipe folder. Once the darkmode.css exists, you can enable Dark Mode in your service settings.

Recipe Dark Mode is only supported by Franz 5.0.0-beta.19+

Debugging

In order to debug your service integration, open Franz and use the shortcut Cmd/Ctrl+Alt+Shift+i to open the recipes developer tools.