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

For segmentation purposes, we provide a dedicated method that you can use directly - no need for complex embedding or extra setup. This method works for both static pages and React integration. All you need to do is call this method from our API object in window. It takes a function as an argument, which returns a segmentation object containing the current user data. The segmentation object itself is a standard JSON format.

window.coolstory.fetchUserData("Pass us a function that returns current user data and we'll take care of the rest")

An example would look like this:

window.coolstory.fetchUserData(function() {
  // Return the current user data in JSON format
  return {
  "userId": "12345",
  "email": "user@example.com",
  "company": "Example Corp",
  "plan": "enterprise",
  "userRole": "admin",
  "lastLogin": "2025-02-12T14:30:00Z",
  "accountStatus": "active",
  "onboardingComplete": true,
  "trialExpired": false
}
});

After creating a segment and adding segmentation criteria in the Segmentation section of the app, and selecting the segment in the story's segmentation settings, the stories will be filtered accordingly.

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 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,
}