Coolstory Docs

Static pages

Let's start with integrating the widget into static pages. This is the easiest method with the fewest steps — copy and paste, add your user ID, and you're all set!

Add this snippet inside the <head> element of your HTML page:

Let's start with integrating the widget into static pages. This is the easiest method with the fewest steps — copy and paste, add your user ID, and you're all set!

Add this snippet inside the <head> element of your HTML page:

<script type="module"
  src="https://app.coolstory.me/widget/widget.js?id=Your user ID"
  ></script>

And place this part anywhere in your HTML page's body to render the story widget:

<div data-coolstory-id="Your widget ID"></div>

That's it! Visit your page and check out your stories!

React projects

This setup is slightly more complex than the previous one, but don't worry - we've got you covered. Here's how to integrate the widget into your React project:

This part should look familiar! Just like before, insert this snippet inside the <head> element of your index.html file:

This setup is slightly more complex than the previous one, but don't worry - we've got you covered. Here's how to integrate the widget into your React project:

This part should look familiar! Just like before, insert this snippet inside the <head> element of your index.html file:

<script type="module"
  src="https://app.coolstory.me/widget/widget.js?id=Your user ID"
  ></script>

And here's a simple React example:

import { useEffect, useRef } from "react";

function App() {        
  const containerRef = useRef<HTMLDivElement>(null);

  useEffect(() => {    
    const widgetContainer = containerRef.current;
    widgetRef.current = window.coolstory?.embedWidget({
      uid: "Your user ID",
      wid: "Your widget ID",
      container: widgetContainer,
    });

  }, []);

  return (
    <>        
      <div ref={containerRef}></div>
    </>
  );
}

export default App;

That's it — your Coolstory widget is now in place!

Types

For TypeScript users, we also provide typings for our API object in window:

type CoolstoryAPI = {
  /**
   * Displays a specific story by its ID.
   * @param storyId - The unique ID of the story to display.
   */
  showStory: (storyId: string) => void;
};

declare global {
  interface Window {
    coolstory: {
      /**
       * Embeds a Coolstory widget into a container element.
       * @param options - Configuration options for the widget.
       * @returns An API object for interacting with the widget.
       */
      embedWidget: (options: {
        uid: string; // The unique user ID.
        wid?: string; // (Optional) The widget ID.
        customTriggered?: boolean; // (Optional) Whether the widget is triggered manually.
        container: HTMLElement; // The DOM container where the widget is embedded.
      }) => CoolstoryAPI;
      /**
       * Mehod specifically designed to provide us with your current widget user
       * data for applying segmentation to widget's displaed stories list.
       * Takes fetcher function as an argument.
       */
      fetchUserData: (
        fetchMetadata: () => SegmentFilters | Promise<SegmentFilters>
      ) => void;
    };
  }
}

Custom trigger

You may have already noticed the dedicated showStory method. This allows you to trigger the widget and display a story with a specific ID - provided that the story is part of the widget's story list. This can be useful, for example, if you want to show a story as soon as the page loads. Additionally, you can hide the widget and its story list from the page by passing a customTriggered argument. Here's an example of how to use it:

import { useEffect, useRef } from "react";

function App() {
  const containerRef = useRef<HTMLDivElement>(null);
  const widgetRef = useRef(null);

  const handleClick = () => {
    widgetRef.current?.showStory("Your story ID");
  };

  useEffect(() => {
    const widgetContainer = containerRef.current;
    widgetRef.current = window.coolstory?.embedWidget({
      uid: "Your user ID",
      wid: "Your widget ID",
      container: widgetContainer,
    });
  
  }, []);

  return (
    <>
      <div ref={containerRef}></div>
      <button onClick={handleClick}>Show Story</button>
    </>
  );
}

export default App;

Segmentation

By default, all stories are visible to all users. Segmentation rules can be applied to individual stories to control visibility.

A story with no segmentation rule is always visible to everyone.
A story with a segmentation rule is only visible to users whose segmentation profile matches that rule.
Users with no segmentation profile will only see stories that have no segmentation rules applied.

To apply segmentation to your stories, you can pass a getSegmentationConfig function in the embedWidget options. This function should return an object containing the current user data that will be used to filter stories.

By default, all stories are visible to all users. Segmentation rules can be applied to individual stories to control visibility.

A story with no segmentation rule is always visible to everyone.
A story with a segmentation rule is only visible to users whose segmentation profile matches that rule.
Users with no segmentation profile will only see stories that have no segmentation rules applied.

window.coolstory.embedWidget({
  uid: "Your ID",
  wid: "Your widget ID",
  container: document.getElementById("widget-container"),
  getSegmentationConfig: () => ({
    // Your user data here
    user_role: "admin"
  })
});

After that, the story list in the widget will be customized for each user based on their data and the configured segmentation settings for the widget.

Event tracking

If you would like to track widget interactions, you can enable Event Tracking in the story options. Once enabled, the widget will begin sending the following events to the data layer: story_clicked, story_viewed, story_closed, finished_viewing and cta_pressed . The data layer is an array of event objects stored within window and can be accessed via window.dataLayer. Event objects follow this structure:

{
  event: Event name,
  story_id: ID of the story where the event occurred,
  story_name: Name of the story where the event occurred,
  widget_id: Widget from which the event was emitted,
}