Booya 2.0 Installation

Booya 2.0: Installation Guide

Sign Up to Booya

1) Go to http://go.booya.io/


 

2) Click "Sign In with HubSpot"


You’ll be redirected to HubSpot, Sign In (if necessary) and choose the portal (if you have multiple) you want to integrate with Booya

 

3) Accept the request for integration permissions


This allows Booya to grant you access to right Integrations based on your HubSpot account. You’ll be redirected back to Booya after granting access.

4) Booya Dashboard


Hubspot will redirect you back to the Booya dashboard after successful authentication. You’re now ready to set up your integrations.

 

Set up an Integration

1) Go to "Integrations" 


Either using the white card on the Dashboard that says "Integrations" or the left sidebar navigation item.

2) Create a new integration or manage/edit/update an existing integration 


Use the "+create" button on the top right to create a new integration or click on an already existing integration’s name in the "Label" column of the "Integrations" list to manage/edit/update an existing one.




3) Connect your HubSpot Portal


Click the "Connect your HubSpot Portal" button in the top right corner.



You’ll be redirected to HubSpot, Sign In (if necessary) and choose the portal (if you have multiple) you want to connect to your Booya Integration


Accept the request for Integration permissions and you’ll be redirected back to Booya..

The fields App "App ID", "HubSpot Portal ID", "HubSpot Refresh Token" and code snippets will automatically be added to your Integration. Additionally, more settings will become available for you to configure.


NOTE: the "HubSpot Portal ID" will also be used to manage access to the integration

4) Set up HubSpot forms


Booya automatically creates forms for Registration, Profile and Verification. However, you can set custom forms for each by copying their IDs (GUIDs) into the "Hubspot Registration Form ID", "HubSpot Profile Form ID" and "Hubspot Verification Form ID" respectively.




The Registration form is submitted with user’s profile information when a user signs up.


The Profile form is submitted with user’s profile information when a user completes or updates their profile.


The Verification form is submitted when a user is identified by Booya for the first time and allows you to associate their browser activity with their HubSpot contact, it should only contain an email field.


Follow this guide to create a HubSpot form

Follow this guide to learn how to find the form ID (GUID) of a HubSpot form


NOTE: For version 0.2.7 and higher of the Booya UI Library, changes made to the Registration and Profile forms are synchronized with the authentication widget shown on your website.


5) Set up OAuth providers


Configure Oauth providers (Facebook, Google, LinkedIn, Twitter etc) by enabling the provider and adding OAuth credentials (typically Client ID/App ID and Client Secret/App Secret)



Follow the following guides for creating apps for various Authentication providers. Find the appropriate callback URL for each provider in Booya Dashboard. The Booya domain to whitelist is auth.booya.io (Facebook refers to this as the App Domain).

Facebook:

Guide https://developers.facebook.com/docs/app-ads/app-setup/

Create an app https://developers.facebook.com/apps/

Google:

Guide: https://support.google.com/cloud/answer/6158849?hl=en

Create a project https://console.developers.google.com/cloud-resource-manager


LinkedIn:

Create an app https://www.linkedin.com/developers/apps

Twitter:

Apply for developer account https://developer.twitter.com/en/application/use-case

Create an app https://developer.twitter.com/en/apps

   

Set up Email authentication 


Email Authentication relies on MailGun to send transactional emails for account verification and password recovery. These emails will automatically be customized to use your "App Name", "Website URL" and "Logo". You can also optionally set an "Email Sender Name" and "Password Reset URL" if you have a customized page for password reset.




NOTE: Booya stores passwords as Bcrypt hashes in a MongoDB database for email authentication.

NOTE:  Remember to make sure that your MailGun emails match, using one domain for configuration and a different email sender will cause issues.

Activate your Booya subscription

1) Navigate to the integration


Either using the white card on the Dashboard that says "Integrations" or the left sidebar navigation item.

 

2) Apply a coupon code (Optional)


If you are provided with a Coupon code, You can add it to one of your integrations. Add your coupon code in the "Coupon Code" field to the left of the "Pay Subscription". 

A confirmation message will appear if the coupon code is valid and has been applied, otherwise an error will be displayed.

3) Make a payment/subscribe via Stripe


Click the "Pay Subscription" button at the top right to set up your payment. You’ll be redirected to Stripe to complete the payment/subscription. 

Note that every individual integration group requires its own subscription license. Booya will ask for one subscription license for every integration.

Add Booya to your website

1) Enable Booya


IMPORTANT: This snippet is already included in BRiX templates so it doesn't need to be added for BriX users.


Copy the code snippet from "Code Snippet: Enable Booya" from the Integration page and add it to your website or portal.



NOTE: Preferably, this should be added in the head area of all your pages. Follow this guide for HubSpot websites for additional help.


2) Add Authentication UI to a section, page or module


Copy the code snippet from "Code Snippet: Render Authentication UI" from the Integration page and add it to the relevant section, page or module of your website.


This code snippet will add an authentication widget with sign in, sign up and recover password forms with links that allow the user to switch between different forms.


NOTE: For version 0.2.7 and higher of the Booya UI Library, changes made to the Registration form in HubSpot are synchronized with this authentication widget.

3) Redirect user to a different page after sign in or logout


Set the "Member URL" and "Guest URL" in the Admin Dashboard under "Authentication Settings". Users will be redirected to the "Member URL" after sign in and to the "Guest URL" after logout.


For more advanced redirect behaviour on sign in based on contact properties on sign in, check the "Enable Advanced Member URL Configuration" and add an option for each redirect based on a contact property value.



NOTE: With "Member URL", "Guest URL" and optionally "Advanced Member URL Configuration" configuration setup.

  • Users will be redirected to the "Member URL" or a matching url in "Advanced Member URL Configuration" after signing in.
  • Users will be redirected to "Guest URL" on logging out.
  • Logged in users landing on the "Guest URL" will be redirected to the "Member URL" or a matching url in "Advanced Member URL Configuration".
  • Logged out users landing on "Member URL" or any url in the "Advanced Member URL Configuration" will be redirected to the "Guest URL".

    NOTE: This requires version 0.2.21 or higher of the Booya UI Library.


4) Add a user widget after authentication and remove it on logout


IMPORTANT: For BRiX users, this functionality is included in the "Authentication" module, so the snippets below should only be for more advanced customization of the default authentication behaviour.


The user widget shows the user’s avatar and name and includes options to "Edit Profile" and "Sign Out" on hover/focus.

HTML:

<!-- Add a wrapper for the user widget to the page HTML -->

<div id="booya-user-wrapper"></div>


JavaScript:

booya.ready(function () {

  // Listen for sign in event

  booya.on(booya.events.IDENTIFY_SUCCESS, function (e) {

    // Add the user widget

    booya.widgets.renderUserWidget("#booya-user-wrapper");

  });


  // Listen for logout event

  booya.on(booya.events.LOGOUT_SUCCESS, function (e) {

    // Remove user widget

    // This is necessary if you don’t redirect user away from the page
    $("#booya-user-wrapper").html("");

  });

});


4) Edit Registration/ Sign Up and Profile Forms


Changes made to the forms set as "HubSpot Registration Form ID" (named "Booya: Registration Form" by default) and "HubSpot Profile Form ID" (named "Booya: Profile Form" by default) in HubSpot will reflect in the Sign Up and Edit Profile forms on your website. 


IMPORTANT: 

  1. Both HubSpot forms should include an email field otherwise submissions from your website will fail because submissions need to be associated with a contact.

  1. The registration form in HubSpot shouldn’t include a password field, this field is automatically added by Booya and passwords are NOT stored in HubSpot. Booya stores passwords as Bcrypt hashes in a MongoDB database for email authentication.

  1. While the profile form in HubSpot must include an email, this field will not be shown on your website because it’s autofilled by Booya when submitting to HubSpot.

  1. This requires version 0.2.7 or higher of the Booya UI Library.

Booya UI Elements library

1) Generating HTML for Booya UI elements (e.g forms, modals and widgets)


Below is a list of all available methods for generating HTML for common Booya UI elements.


Method

Arguments

Description

renderSignInForm

title, fields, action, options

Renders a sign in form with email and password fields by default

renderSignUpForm

title, fields, action, options

Renders a sign up/register form with email, password, first_name, last_name and phone fields by default

renderVerifyForm

title, fields, action, options

Renders a verify form with an email field by default

renderRecoverForm

title, fields, action, options

Renders an account recovery form with an email field by default

renderResetForm

title, fields, action, options

Renders an password reset/change form with  password and confirm password fields by default

renderProfileForm

title, fields, action, options

Renders a sign up/register form with first_name, last_name and phone fields by default

renderModal

*title, *content, options

Renders a modal

renderAuthWidgets

*options

Renders a widget with Sign In (with OAuth buttons), Sign Up and Recover forms with links that switch between the forms. Settings for the forms are dynamically read from Booya Admin.

renderUserWidget

target, options

Renders a user widget that shows the user’s avatar and name and includes options to "Edit Profile" and "Sign Out" on hover/focus.


NOTE: All methods can be accessed via booya.widgets.* e.g booya.widgets.renderAuthWidgets()


NOTE: Arguments prefixed with * are required





2) Adding UI elements to the page 


HTML:

<!-- Add a wrapper for the UI element to the page HTML -->

<div id="booya-wrapper"></div>


JavaScript:

NOTE: All Booya code should be wrapped inside a ready callback to allow deferred loading of the UI library e.g

booya.ready(function () {

  // Code goes here

});


Authentication Widget: 

/* Add an auth widget with all options for user     registration including Sign In, Sign Up, Recovery and OAuth with links that switch between options */

booya.widgets.renderAuthWidgets({

  target: "#booya-wrapper"

}); 


Authentication Widget - Modal: 

booya.widgets.renderAuthWidgets({

  target: "#booya-wrapper",

  modal: {isOpen: true}, // isOpen will automatically open the modal

});


Authentication Widget - MultiStep: 

/* Request email first and show either Sign In or Sign Up form depending on user’s status */

booya.widgets.renderAuthWidgets({

  target: "#booya-wrapper",

  multiStep: true,

});

NOTE: This integration requires version 0.2.4 or higher of the Booya UI Library


Authentication Widget - Magic Link sign in enabled: 

/* Request email first and show either Sign In or Sign Up form depending on user’s status */

booya.widgets.renderAuthWidgets({

  target: "#booya-wrapper",

  magicLink: true,

});

NOTE: This integration requires version 0.2.6 or higher of the Booya UI Library


Authentication Widget - No Sign In: 

/* Request email first and show either Sign In or Sign Up form depending on user’s status */

booya.widgets.renderAuthWidgets({

  target: "#booya-wrapper",

  signIn: false,

});

NOTE: This integration requires version 0.2.6 or higher of the Booya UI Library


Authentication Widget - No Sign Up: 

/* Request email first and show either Sign In or Sign Up form depending on user’s status */

booya.widgets.renderAuthWidgets({

  target: "#booya-wrapper",

  signUp: false,

});

NOTE: This integration requires version 0.2.6 or higher of the Booya UI Library



Authentication Widget - No Account Recovery: 

/* Request email first and show either Sign In or Sign Up form depending on user’s status */

booya.widgets.renderAuthWidgets({

  target: "#booya-wrapper",

  recover: false,

});

NOTE: This integration requires version 0.2.6 or higher of the Booya UI Library


Sign In form: 

// Add a sign in form to the wrapper

$("#booya-wrapper").html(

  booya.widgets.renderSignInForm()

);

booya.initUI(); // Not necessary if a target is added via "options"


Sign In form - Modal:

// Add a sign in form wrapped in a modal to the wrapper

booya.widgets.renderModal(

  "Sign In", 

  booya.widgets.renderSignInForm(),

  {

    target: "#booya-wrapper",

    modal: {isOpen: true},

  }

);


Sign Up form: 

// Add a sign up form to the wrapper

$("#booya-wrapper").html(

  booya.widgets.renderSignUpForm()

);

booya.initUI(); // Not necessary if a target is added via "options"


Sign Up form - Customized:

// Add a customized sign up form to the wrapper

booya.widgets.renderSignUpForm(

  "<h2>Register</h2>", // Custom Title

  "<input name="email" type="email" required/>" + // Customized Fields

  "<input name="password" type="password" required/>" +

  "<input name="first_name" type="text" required/>" +

  "<input name="last_name" type="text" required/>",

  "Register", // Custom Action

  {

    "target": "#booya-wrapper",      

    "error": "Something’s wrong" // Custom error message

    "success": "Awesome", // Custom success message

    "warning": "Bad data", // Custom validation message

  } 

);

Booya Events

1) List of available events



Name

Constant

Data

Description

booya-ready

READY

N/A

Fired when booya is fully initialized (portalID and appID are set up) 

booya-identify-success

IDENTIFY_SUCCESS

user

Fired when a user is identified (e.g either when they login or a new page is loaded for an existing session)

booya-identify-failed

IDENTIFY_FAILED

user

Failure version of "booya-identify-success"

booya-verify-email-success

VERIFY_EMAIL_SUCCESS

email

Fired as the success event for two legged sign in and sign up flows where an email is first entered before either a registration form is shown or a password form is shown. 

A password form should be displayed when this event is fired

booya-verify-email-failed

VERIFY_EMAIL_FAILED

email

Failure version of "booya-verify-email-success". 

A registration form should be displayed when this event is fired 

booya-logout-success

LOGOUT_SUCCESS

 

Fired when a user logs out

booya-logout-failed

LOGOUT_FAILED

 

Failure version of "booya-logout-failed"

booya-magic-link-request-success

MAGIC_LINK_REQUEST_SUCCESS

 

Fired when a magic link is requested successfully.

booya-magic-link-request-failed

MAGIC_LINK_REQUEST_FAILED

 

Failure version of "booya-magic-link-request-success"

booya-magic-link-verify-success

MAGIC_LINK_VERIFY_SUCCESS

 

Fired when a user is logged in with a magic link successfully.

booya-magic-link-verify-failed

MAGIC_LINK_VERIFY_FAILED

 

Failure version of "booya-magic-link-verify-success"



NOTE: All event constants can be accessed via booya.events.* e.g booya.events.IDENTIFY_SUCCESS for "booya-identify-success"

2) How to listen for events


booya.on(booya.events.IDENTIFY_SUCCESS, function (e) {

  // Log user data

  console.log("user identified", e.user);

});


NOTE: Event listeners should be wrapped inside booya.ready callbacks

    Common Integrations

    1) HubSpot Chat Widget


    This integration allows you to pass the identity of authenticated users from Booya to your HubSpot chat widget.

     

    /* Step 1: Disable Immediate Loading */

    window.hsConversationsSettings = {

      loadImmediately: false,

    };

     

    /* Step 2: Pass identity to HubSpot when authentication succeeds */

    booya.ready(function () { // Start of ready callback

      

      booya.on(booya.events.IDENTIFY_SUCCESS, function (e) {

        // Get user data

        var user = e.user;

      

        // Generate a HubSpot user identification token

        booya.createHSChatToken(function (token) {

          if(token) {

            // Set the user’s identity

            window.hsConversationsSettings = {

              identificationEmail: user.email,

              identificationToken: token,

            };

          }

        

          // Load the chat widget

          window.HubSpotConversations.widget.load();

        });

      }); // End of identity success callback

      

    }); // End of of ready callback

     

    /* Step 3: Load the chat widget for unidentified visitors */

    booya.on(booya.events.IDENTIFY_FAILED, function (e) {

      // Load the chat widget

      window.HubSpotConversations.widget.load();

    });


    NOTE: This integration requires version 0.2.4 or higher of the Booya UI Library

    Advanced Integrations

    1) REST API


    Booya authentication can be leveraged on any platform or environment by consuming Booya’s REST API. See the Booya REST API documentation for more details.

    2) Access Token Verification


    Access tokens issued by Booya can be verified from any environment using the Verify Token endpoint as described in the Booya API documentation.

     

    An API Client is also available for Node.js for easier integration

    NPM - https://www.npmjs.com/package/@inboundlabs/booya-api-client

    GitHub - https://github.com/InboundLabs/booya-api-client