What’s new in Typeform Embed SDK — 2023 update
It’s been a year since the last update on new Embed SDK features. I promised this to be a series, and as it turns out, it is a series with articles on an annual basis. It’s something, right?
So what’s new this time?
HubSpot integration
Are you building lead generation typeforms? You can connect your typeform with HubSpot. When you do, a few hidden fields will be automatically created for you:
- hubspot_page_name
- hubspot_page_url
- hubspot_utk
To properly track and attribute your leads, the next step is to setup source tracking as explained in this Help Center article. For embedded typeforms this means you need to populate those hidden fields with data — from your page and Hubspot cookie.
We have automated this process. All you need to do is pass data-tf-hubspot / hubspot attribute to your embedded typeform like this:
<div data-tf-widget="<form-id>" data-tf-hubspot></div>
<script src="//embed.typeform.com/next/embed.js"></script>The Embed SDK will populate the hidden fields for you:
- hubspot_page_name — the title of your page (from document.title)
- hubspot_page_url — the page URL (from window.location.href)
- hubspot_utk — value from hubspotutk cookie
Setting the hubspot_utk value is the complex part. First, we need to wait for HubSpot tracking code to set the value (in case it is not set yet). This is an asynchronous operation that usually does not take more than a few milliseconds. However, to load the value correctly, the typeform must wait for the cookie to be set. Since the wait time is in most cases very low, it does not affect perceived load time and performance of your embedded typeforms.
Note: If you enable HubSpot integration in your embed code (via data-tf-hubspot / hubspot attribute) and do not include HubSpot tracking code in your page, it can delay the loading of your typeform by up to 2.5 seconds. Therefore it is important to enable this feature only if you are using HubSpot on your page.
Callback for ending button click
Last year, we added a redirect target to specify where to open the URL on the redirect. You can redirect the respondent inside the embedded iframe, in place of the host page, or even in a new tab.
We took it one step further and introduced a callback for when the button on an end screen is clicked — onEndingButtonClick. An onSubmit callback is already fired when your typeform is submitted. However, this is the perfect callback for you if you’d like to display the end screen before executing your logic.
For example, you could close the popup window with your form when the ending button is clicked:
<button id="btn">open popup</button>
<link rel="stylesheet" href="//embed.typeform.com/next/css/popup.css:" />
<script src="//embed.typeform.com/next/embed.js"></script>
<script>
const { open, close } = window.tf.createPopup("<form-id>", {
onEndingButtonClick: () => {
close()
}
})
document.querySelector("#btn").onclick = open
</script>UX optimizations on mobile devices
We improved the experience on mobile devices for typeforms embedded in full-screen mode. When any browser toolbars are displayed or hidden, your typeform is resized to fit the current viewport and not to be covered by browser UI.
The same auto-resize is also available out-of-the-box for typeforms embedded as popups to ensure your form (especially the “Start” button on the welcome screen) is not hidden under browser toolbars.
Disable scrolling and swiping
Navigating within a typeform feels very natural. You can scroll or swipe between questions. You can navigate like this both forward and backward. However, when embedding a typeform (as a widget) this feature might conflict with the navigation in your website or app.
To prevent this, you can supply data-tf-disable-scroll / disableScroll attribute to your embed.
The only way to navigate between questions is by answering and submitting them or using the arrows at the bottom right corner.
Custom refs for Typeform React Embed Library
If you need to build some advanced functionality using our React Embed SDK, you can pass ref prop like this:
import { createRef } from 'react'
import { SliderButton } from '@typeform/embed-react'
const MyComponent = () => {
const sliderRef = createRef()
useEffect(() => {
if (/* custom logic */) {
sliderRef.current?.open()
}
}, [ sliderRef ])
return <SliderButton id={id} ref={sliderRef}>open</SliderButton>
}With the code above, you can programmatically open or close your typeform embedded as a slider.
Hidden field value priority
Did you know there are multiple ways to pass value to your hidden fields? You have 2 options. You can set it to:
- hardcoded value via data-tf-hidden / hidden attribute
- dynamic value based on your host page URL via data-tf-transitive-search-params / transitiveSearchParams attribute
But what if you define both? Which value will be used?
1. Generic transitive search params
<div
data-tf-widget="<form-id>"
data-tf-transitive-search-params
data-tf-hidden="foo=bar"
/>If you define transitive search params as a generic (an attribute with no value or pass true when using the JS API), the value from the hidden field will always be used.
In this example, your hidden field foo will always have a value bar even if you pass a different value in the URL (e.g. ?foo=foobar).
2. Specific transitive search params
<div
data-tf-widget="<form-id>"
data-tf-transitive-search-params="foo"
data-tf-hidden="foo=bar"
/>With a specific hidden field defined in transitive search parameters, you can overwrite the value via the URL of your host page. If you pass a value in the URL it will be used in place of the default value defined in the data-tf-hidden attribute.
In this example, the value of your hidden field foo will be bar. However, if you pass a different value in the URL (e.g. ?foo=foobar), it will use the value from the URL, and the hidden field value is now foobar.
What to use this for?
You can use this approach to define hard-coded hidden fields that can not be overwritten via URL (example 1) or a dynamic hidden field with a fallback to default value when not specified in URL (example 2).
Which feature is your favorite? Are you missing anything? Reach out on Twitter @mathio28, leave a comment on our GitHub, or talk to the community of Typeform developers.
