@gobistories/gobi-web-integration
    TypeScript icon, indicating that this package has built-in type declarations

    6.13.10 • Public • Published

    Gobi Web Integration

    Welcome to Gobi Web Integration. This library will let you put your Gobi stories on your site. If you don't have any Gobi Stories yet sign up in our Story Manager to get access to our production tools.

    Story Bubbles Demo

    See a demo of this library in action at https://www.gobistories.com/developers

    To easily test the most used options, go to the code snippet editor in our Story Manager.

    Troubleshooting & FAQ

    Bubbles don't show

    See the console. Can you spot any errors? Try to understand them. If there seems to be a bug in the library, please email us.

    The player doesn't open and I see CORS errors

    If you have a website where the server uses the Content-Security-Policy HTTP header, it must include blob: in default-src or media-src. Domains used by our library are:

    • api.gobistories.co
    • api.gobistories.com
    • res.cloudinary.com/gobi-technologies-as

    My page scrolls when opening a story

    If your page scrolls to the top when opening a story, this is usually caused by the height styling for the HTML tag of your page. Removing or replaceing this with min-height usally solves the problem.

    Technical Documentation

    Story Bubbles

    Adding bubbles to your pages and content requires three steps:

    1. Load our script
    2. Add a placeholder element where you want the bubbles
    3. Call our code to create the bubbles

    You can generate the required code within our Story Manager, or refer to the documentation below.

    Adding bubbles with Gobi.discover()

    This is the recommended way to add story bubbles to your page. Add your placeholder where you want the bubble to appear, add the gobi-stories class and specify options using data attributes:

    <div
      class="gobi-stories"
      data-gobi-stories="story-id another-story-id"
      data-gobi-kebab-cased-option="value"
      data-gobi-some-other-kebab-cased-option="value"
    ></div>

    See the Bubble Options section for available options. Note that options should be converted to kebab case and prefixed with data-gobi-.

    You can then load our script and run gobi.discover():

    <head>
      <script
        src="https://unpkg.com/@gobistories/gobi-web-integration@^6"
        async
        onload="gobi.discover()"
      ></script>
    </head>

    You can pass global options to discover() that will be used for all bubbles on the page as defaults:

    gobi.discover({
      bubbleSize: '120px',
      color: 'blue',
    });

    The global options will be used when they are not overridden by individual embed options.

    Adding bubbles with an inline script

    Another way to add Gobi stories to your page is by using inline javascript.

    <head>
      <script src="https://unpkg.com/@gobistories/gobi-web-integration"></script>
    </head>
    <body>
      <div id="container"></div>
      <script>
        new gobi.Bubbles({
          container: '#container',
          stories: [
            {
              id: 'story-key',
              title: 'Some Title',
            },
            {
              id: 'another-story-key',
              title: 'Some Another Title',
            },
          ],
        });
      </script>
    </body>

    Creating a standalone player

    You can also show story player directly in the page without using bubbles.

    <head>
      <script src="https://unpkg.com/@gobistories/gobi-web-integration"></script>
    </head>
    <body>
      <div id="container"></div>
      <script>
        new gobi.Player({
          container: '#player-container',
          storyId: 'story-key',
          on: {
            videoPlay: function() {
              console.log('played the video!');
            },
          },
        });
      </script>
    </body>

    See Player Options for details.

    Installing as a Package

    npm version

    Developers may prefer to install Gobi Web Integration as a package dependency:

    npm install --save @gobistories/gobi-web-integration
    import { Bubbles } from '@gobistories/gobi-web-integration';
    
    // Create bubbles
    new Bubbles({
      container: '#container',
      bubbleSize: '200px',
    });
    
    // Create a Player
    new Player({
      container: '#container',
      storyName: 'story-id',
      playerOptions: {
        on: {
          videoPlay: function() {
            console.log('played the video!');
          },
        },
      },
    });

    Browser Support

    The library will work well in Chrome, Firefox, Safari, and Opera. The library lets users in IE view the story, but UX and functionality might be a bit limited compared to modern browsers.

    Bubble Options

    option default description
    container #gobi-here Required for inline javascript. String. Query Selector for HTMLElement. Container where the module will be embed.
    color #15d6ea Any valid css color value (#000, rgb(...), rgba(...)). The color of the border around the story bubble.
    bubbleSize 96px Valid css size value, except % (10px, 10vw...). The size of the avatar aka bubble.
    hideTitle false Boolean. Hides the bubble title if true (default false)
    animatedBubble false Boolean. Makes the bubbles as gif animation.
    wrap false Boolean. Add styles which allow a horizontal series of bubbles to wrap to new lines, when the screen is narrow.
    isFullHeightMobile true Boolean. Add styles which allow making a full-screen popup. It's work only on mobile phone
    showPlayIcon false Boolean. Add Play icon inside the bubbles
    playIconUrl undefined Optional string, will show the given icon in the play bubble.
    align center String. Valid values 'left', 'right', 'end', 'start', 'center' . It sets alignment for bubbles horizontally
    autoSegue false Boolean. Enable or disable the transition to next story in the end
    fullscreenPlayer false Boolean. Set to true to remove all margins from the player when opened in popup mode
    noShade false Boolean. Set to true to not apply a page background shade when the player is opened in popup mode
    titleFontSize 12px Valid css size value. By default, a size is selected based on bubbleSize between 12px and 36px.
    titleFontColor black Any valid css color value (#000, rgb(...), rgba(...)). The color of the bubble title text.
    titleFontFamily undefined Valid css font family name. Inherited from the document by default.
    titleFontWeight undefined Valid css font weight. Inherited from the document by default.
    inheritTextFontFamily false Boolean. Whether to inherit the font family from the page for bubble titles.
    inheritTextStyles false Boolean. Whether to inherit font family, font size, font weight and color from the page for bubble titles.
    zIndex 2000000 Number. Sets the priority of the player above other content when open.
    on.loaded function Function. Called when all Bubbles have loaded.
    on.close function Function. Called when all popups are closed.
    stories [] Required for inline javascript. Array. Data of stories.
    stories[0...n].id Required. String. Identifire of story.
    stories[0...n].title String. Change title text of specific story.
    stories[0...n].thumbnailUrl String. Overrides the image used for the bubble.
    stories[0...n].bubbleSrc Deprecated. Alias of thumbnailUrl.
    playerOptions {} Object. Provides options to the player when opening. See Player Options for details.

    Embedded player

    Creates a Player and returns an interface for managing it, and for listening to its events.

    Player Options

    option default description
    container Query Selector for HTMLElement. Container where the player will be inserted.
    storyId Required. String. The key of the story.
    autoStart false Boolean. Add autoplay attributes to the video.
    autoStartWithSound false Boolean. Add autoplay attributes to the video, and don't mute the video at the same time.
    loop false Boolean. Add loop function to video.
    roundedCorners true Boolean. Enable or disable rounded corners to player element.
    shadow true Boolean. Enable or disable shadow on the player element.
    width 612 Number. Set player width. If height is not defined it will calculate automaticaly using an aspect ratio of 16:9.
    height 1088 Number. Set player height. If width is not defined it will calculate automaticaly using an aspect ratio of 16:9.
    checkViewPort true Boolean. Enable functionality which pause player if it outside of screen view area.
    playButton true Boolean. Enable or disable play button.
    savePosition true Boolean. Enable or disable save last watched chapter. It needs to confirm policy by user
    useMediaProxy false Boolean. Enable the use of a reverse proxy hosted by Gobi for media content.
    on [] Array. Data of event listener
    on.videoPlay function Called when the video plays.
    on.videoPause function Called when the video pauses.
    on.videoComplete function Called when the video completes.
    on.clickPrevious function Called when changing to the previous chapter.
    on.clickNext function Called when changing to the next chapter.
    on.clipChange function Called when a chapter changes.
    on.newIteration function Called when the story loops back to the beginning (requires loop to be true).
    on.error function Called when an error occurs.
    on.loaded function Called when the video is loaded.

    Events

    All events are called with the relevant chapter index as the first parameter.

    Methods

    You can destroy the Gobi Player to free up resources:

    var player = new gobi.Player({
      container: '#player-container',
      storyId: 'story-key',
    });
    
    player.destroy();

    Gobi Stories Public API

    Our public HTTP API can be queried to fetch story renders from the base url https://api.gobistories.com.

    GET /renders/:viewKey

    Fetches a story render - the data required to display a published story. This is particularly useful for fetching thumbnail urls for creating custom story previews, buttons and links.

    URL Parameters

    Parameter Type Description
    :viewKey string The identifier for the story.

    Response JSON

    {
      viewKey: string;
      version: number;
      title: string;
      videoUrl: string;
      streamingUrl: string;
      thumbnailUrl: string;
      animatedThumbnailUrl: string;
      webmThumbnailUrl: string;
      mp4ThumbnailUrl: string;
      posterUrl: string;
      chapters: {
        id: string;
        order: number;
        duration: number;
        stickers: {
          type: "TEXT" | "LINK" | "DUMB";
          order: number;
          x: number;
          y: number;
          scale: number;
          rotation: number;
          imageUrl: string | null;
          linkUrl: string | null;
          text: string | null;
        }[];
      }[];
      whiteLabel?: boolean;
    }

    Install

    npm i @gobistories/gobi-web-integration

    DownloadsWeekly Downloads

    1,162

    Version

    6.13.10

    License

    Apache-2.0

    Unpacked Size

    938 kB

    Total Files

    110

    Last publish

    Collaborators

    • gobi-darren
    • andreaog