DIY Quick Start Guide: Node.js

This guide is for developers adding Bread & Butter sign-in to their own website or app with a Node.js backend. You use the Bread & Butter JavaScript Library on the front end to show the sign-in options, and the Bread & Butter Node.js library on your server to receive each visitor's verified details and create their account or session.

In short: Add the JavaScript Library to every page and configure it with your App ID. That tracks visitors and, with BreadButter.ui.continueWith() , shows the "Continue with" sign-in prompt. When a visitor signs in, Bread & Butter sends them to a callback URL on your server with a token. Your Node.js code uses the breadbutter-nodejs library, your App ID and an App Secret to exchange that token for the visitor's email address, name and profile image, then creates their session and redirects them to the destination URL. Load the stable version of the JavaScript Library so you always get fixes and new features.

Before you start

You'll need:

Your App ID. Find it in the Bread & Butter dashboard under Settings, then App & Domains.
An App Secret, for the server side. Create one under Settings, then App & Domains, in the Advanced: App Secrets section. It's shown only once, so copy it straight away. Keep it on your server and never put it in front-end code.
The libraries. The JavaScript Library and the Node.js library are both on GitHub.

Step 1: Add the JavaScript Library to your pages

This snippet loads Bread & Butter and shows the "Continue with" sign-in prompt. Put it in your site's header or main template so it runs on every page.

<script>
window.initBreadButter = function() {
    BreadButter.configure({ app_id: APP_ID });
    BreadButter.ui.continueWith();
};
(function(d, s, id){ var js,fjs=d.getElementsByTagName(s)[0]; if(d.getElementById(id)) {return;} js = d.createElement(s); js.id = id; js.src = 'https://cdn.breadbutter.io/dist/breadbutter.stable.min.js'; fjs.parentNode.insertBefore(js, fjs); }(document, 'script', 'breadbutter-js'));
</script>

Replace APP_ID with your App ID.

What each part does:

initBreadButter runs once the library has loaded. Put any Bread & Butter calls inside it.
BreadButter.configure({ app_id: APP_ID }) connects the page to your app. Every page with this line tracks visitors, and their activity appears in your dashboard.
BreadButter.ui.continueWith() shows the "Continue with" prompt to visitors who haven't signed in, with the sign-in options you've turned on, such as Google. Remove it from pages where you don't want visitors prompted, or leave it out altogether if you don't want to use the prompt.

Use the stable version

The snippet loads breadbutter.stable.min.js , which always points to the current stable release. Older snippets load a fixed version number instead, such as breadbutter.8.5.0.35.min.js , and stay on that version until someone changes it by hand. That means they miss fixes and new features, and can stop working correctly with newer parts of Bread & Butter. If your site loads a numbered version, replace it with breadbutter.stable.min.js .

Step 2: Create a callback route on your server

When a visitor signs in, Bread & Butter processes it and sends them to a callback URL on your site, with an authentication_token . Create a route at that URL to receive it.

Install the Node.js library

npm install breadbutter-nodejs --save

Create a Bread & Butter client

Replace APP_ID and APP_SECRET with your own values.

const client = require('breadbutter-nodejs')('APP_ID', 'APP_SECRET');

Get the visitor's details and send them on

This example uses Express. Other servers work the same way, but how you read the token and redirect may differ.

app.use(function(req, res) {
    const authToken = req.query.authentication_token;

    client.getAuthentication(authToken).then((response) => {
        const authData = response.auth_data;

        const emailAddress = authData.email_address;
        const firstName = authData.first_name;
        const lastName = authData.last_name;
        const profileImage = authData.profile_image_url;
        // Use the details above to create the user in your system, start a session, etc.

        const destinationURL = response.options.destination_url;
        res.redirect(destinationURL);

        // Without Express:
        // res.writeHead(301, {
        //     Location: destinationURL
        // }).end();
    });
});

Step 3: Set your callback URL

In the Bread & Butter dashboard, open your advanced settings, go to the Callback URL section, enter the URL of the callback page you created in Step 2, and turn the callback URL on. Include https:// .

Your sign-in is now live. Visitors who sign in through the "Continue with" prompt are sent to your callback route, signed in to your system and returned to your site.