calcom/packages/embeds/embed-core

embed-core

See index.html to understand how it can be used.

Features

• The Embed SDK can be added asynchronously
  • You can add it through any tag manager like GTM if you like[Need to Test]
• Available configurations are
  • theme
  • Prefilling of
    • name
    • email
    • notes
    • guests

How to use embed on any webpage no matter what framework

• Step-1. Install the snippet

  (function(C, A, L) {
  let p = function(a, ar) {
    a.q.push(ar);
  };
  let d = C.document;
  C.Cal = C.Cal || function() {
    let cal = C.Cal;
    let ar = arguments;
    if (!cal.loaded) {
      cal.ns = {};
      cal.q = cal.q || [];
      d.head.appendChild(d.createElement("script")).src = A;
      cal.loaded = true;
    }
    if (ar[0] === L) {
      const api = function() {
        p(api, arguments);
      };
      const namespace = ar[1];
      api.q = api.q || [];
      typeof namespace === "string" ? (cal.ns[namespace] = api) && p(api, ar) : p(cal, ar);
      return;
    }
    p(cal, ar);
  };
  })(window, "https://cal.com/embed.js", "init");
  

• Step-2. Give init instruction to it. It creates a queue so that even without embed.js being fetched, you can give instructions to embed.

  Cal("init) // Creates default instance. Give instruction to it as Cal("instruction")
  

  Optionally if you want to install another instance of embed you can do

  Cal("init", "NAME_YOUR_OTHER_INSTANCE"); // Creates a named instance. Give instructions to it as Cal.ns.NAME_YOUR_OTHER_INSTANCE("instruction")
  

• Step-1 and Step-2 must be followed in same order. After that you can give various instructions to embed as you like.

Supported Instructions

Consider an instruction as a function with that name and that would be called with the given argument.

inline - Appends embed inline as the child of the element.

• elementOrSelector - Give it either a valid CSS selector or an HTMLElement instance directly

• calLink - Cal Link that you want to embed e.g. john. Just give the username. No need to give the full URL https://cal.com/john. It makes it easy to configure the calendar host once and use as many links you want with just usernames

ui - Configure UI for embed. Make it look part of your webpage.

• styles - It supports styling for body and eventTypeListItem. Right now we support just background on these two.

preload - If you want to open cal link on some action. Make it pop open instantly by preloading it.

• calLink - Cal Link that you want to embed e.g. john. Just give the username. No need to give the full URL https://cal.com/john

Development

Run the following command and then you can test the embed in the automatically opened page http://localhost:3002

yarn dev

Shipping to Production

yarn build

Make dist/embed.umd.js servable on URL http://cal.com/embed.js

Upcoming Improvements

• Unsupported Browsers and versions. Documenting them and gracefully handling that.

• Accessibility and UI/UX Issues

  • Loader on ModalBox/popup
  • If website owner links the booking page directly for an event, should the user be able to go to events-listing page using back button ?

• Bundling Related

  • Minify CSS in embed.js

• Debuggability

  • Send log messages from iframe to parent so that all logs can exist in a single queue forming a timeline.
    • user should be able to use "on" instruction to understand what's going on in the system
  • Error Tracking for embed.js
    • Know where exactly it’s failing if it does.

• Improved Demo

  • Seeding might be done for team event so that such an example is also available readily in index.html

• Dev Experience/Ease of Installation

  • Do we need a one liner(like window.dataLayer.push) to inform SDK of something even if snippet is not yet on the page but would be there e.g. through GTM it would come late on the page ?

• Might be better to pass all configuration using a single base64encoded query param to booking page.

• Embed Code Generator

• UI Config Features

  • Theme switch dynamically - If user switches the theme on website, he should be able to do it on embed.
  • Text Color
    • Brand color
    • At some places Text is colored by using the color specific tailwind class. e.g. text-gray-400 is the color of disabled date. He has 2 options, If user wants to customize that
      • He can go and override the color on the class which doesn’t make sense
      • He can identify the element and change the color by directly adding style, which might cause consistency issues if certain elements are missed.
    • Challenges
      • How would the user add on hover styles just using style attribute ?

• React Component

  • onClick support with preloading

Pending Documentation

• READMEs

  • How to make a new element configurable using UI instruction ?
  • Why do we NOT want to provide completely flexible CSS customization by adding whatever CSS user wants. ?

• docs.cal.com

  • A complete document on how to use embed

• app.cal.com

  • Get Embed code for each event-type