Skip navigation

Integrating forms (HubSpot)

In this tutorial, you will learn how you can easily integrate Kentico Kontent with an online marketing solution to enable marketing automation by providing content editors a custom form selector to gather leads through a form included in the site content.

Premium feature

Custom elements require a Professional plan or higher.

Table of contents

    This tutorial shows a specific example tailored to the HubSpot platform, but the same principles can be applied to integration with many more online marketing solutions which provide an API to get a list of forms and the ability to embed the form to an external website.

    The HubSpot Form selector in action.

    What is HubSpot?

    HubSpot is an online marketing platform you can use to easily manage your marketing and sales efforts, and then automate based on this data.

    Content management and HubSpot

    In this tutorial, we will cover a scenario in which we will allow a content editor to assign an existing HubSpot form to a piece of content, and then display it automatically on a live site to collect new leads.

    To keep things simple, assume that both the HubSpot account with some existing form(s), and your Kentico Kontent blogging platform with articles, already exist and you just need to connect the two to achieve your goal.

    Within this integration, you will:

    • Register an application within your HubSpot developer account.
    • Run an instance which provides the custom selector and communication with HubSpot.
    • Add a custom element with a HubSpot Form selector to your content type.
    • Link articles to specific forms.
    • Add a form dynamically to the article page on the live site.

    The setup of the selector and live site presentation needs to be done by a developer, but once it is set up, a content editor or a marketer can work with the forms completely independently without the need to contact the developer.

    Step 1: Register an application within HubSpot

    The custom form selector needs to be able to access the your list of HubSpot forms. In order to allow that, you need to have a developer account registered, as well as an application which represents the selector.

    Navigate to the HubSpot developer portal. If you don't have a developer account registered with HubSpot, create one at the HubSpot developer site.

    Next, navigate to Apps in the developer portal and click Create app.

    • Name - Kentico Cloud
    • Keep the visibility Public and click Create.

    After the application is created, you can find the Client ID and the Client secret in the Details tab. You'll need these two values to properly connect the HubSpot form selector to your account.

    Step 2: Configure and run the HubSpot Form selector

    The HubSpot Form selector uses OAuth to authenticate against HubSpot and is based on the HubSpot OAuth example. Authentication and communication are handled server-side, which is recommended by HubSpot. For more information about OAuth and HubSpot authentication, see HubSpot documentation.

    This means that you need to run your own instance of the HubSpot Form selector instead of using a globally available instance as with many other integrations.

    The complete code of the sample form selector is available in this GitHub repository.

    In order to easily run the selector on your own computer, you need to have NodeJS and git installed.

    Run the following commands from your console:

    • shell
    git clone https://github.com/Kentico/cloud-custom-element-sample-hubspot.git cd cloud-custom-element-sample-hubspot npm install
    git clone https://github.com/Kentico/cloud-custom-element-sample-hubspot.git cd cloud-custom-element-sample-hubspot npm install

    Navigate to server/hubspot.js and replace the constants CLIENT_ID and CLIENT_SECRET with the values from your HubSpot app which was registered in the previous step.

    The form selector will run by default at https://localhost:3000. If you need to use another port, you can change it in the PORT constant in server.js.

    After you finish the configuration, run npm run start from your console. This will run the HubSpot Form selector and make it available at https://localhost:3000. The selector needs to be placed in the Kentico Kontent UI in order for it to properly initialize, so don't try it just yet.

    Note that for production use, you will need to deploy the custom element instance to a publicly available server running NodeJS.

    Step 3: Add a HubSpot Form selector to a Kentico Kontent content type

    In this step, we'll extend the Article content type in our Sample App to include a product selector.

    1. In Kentico Kontent, choose Content models from the app menu.
    2. Open the Article content type.
    3. Add a Custom element.
      • Name it HubSpot form.
      • For the Hosted code URL, enter https://localhost:3000 or the URL of the selector instance which you deployed for production use.
    4. Save the content type.

    Step 4: Link articles to specific forms

    With the content type set up, you can see how the selector works and assign individual articles to their respective forms from HubSpot.

    1. In Kentico Kontent, choose Content & Assets from the app menu.
    2. Filter the list by selecting Article in the Content type filter group.
    3. Click a content item to open it.
    4. Use the form selector to find and select a form from HubSpot.
      • Note that the first time you use the selector, you may need to log in to HubSpot and allow the selector to access the data.
    5. Publish the content item to make sure the data is available on your live website.
    6. Repeat steps 3–5 for other Article items where you wish to place forms.

    Selector value format and customization

    Note that the form selector used in the previous steps is a demo to demonstrate the possibilities. Feel free to adjust it to your needs and visual requirements, or build your own.

    You can find the form selector source code in its GitHub repository.

    The selector stores the following value format in JSON, which it also uses to display the selected form on the first load without the need to authenticate every time:

    • JSON
    { "id": "176bcb4d-cbc3-45f0-b11a-f6230c4360f2", "name": "Contact us", "portalId": "5975142" }
    { "id": "176bcb4d-cbc3-45f0-b11a-f6230c4360f2", "name": "Contact us", "portalId": "5975142" }

    The fields are:

    • id – The internal ID (GUID) of the form in HubSpot.
    • name – The name of the form.
    • portalId - The internal ID of your HubSpot instance which you selected while authenticating against HubSpot and where the form is defined.

    You can use any of those values for both admin UI and your site. Should you need to make more fields available, you can do so by customizing the custom element code.

    Step 5: Present the form on your live site

    With new values in our data model and an understanding of their structure, you can start to actually display a form below the article to start collecting leads.

    This step varies based on the technology you're using to display your content, so let's just briefly summarize what needs to be done.

    First, update your front-end model for the Article content type to include the new custom element.

    Because the value from the selector is provided as a structured object serialized to JSON, you need to parse the value from JSON at some point. You would most typically do that within the conversion of the source data model to the view model that you pass to your rendering code.

    In your rendering code, provide the code to render the HubSpot form under the article and give it the Form ID and the Portal ID. If your website uses server-side rendering, you can use the embed code provided directly in HubSpot's dialog after publishing the form. In our case, the sample site is a React application, therefore we are using react-hubspot-form npm package.

    See a full sample code for displaying a selected form on your website.

    For mobile apps, the easiest way to provide the form is a link to your website or a direct link to the form as provided in the HubSpot dialog after publishing the form.

    What's next?

    You learned how to link your content to online marketing forms in order to provide a lead generation tool on your website.

    The custom form selector sample provides a baseline you can use and further adjust to your needs. Other online marketing solutions may have different endpoints and contracts, but the selector code is easy enough to adjust for other systems.

    You can use a similar approach and build integrations with other online marketing solutions.