6.14.20 • Published 14 days ago

@gobistories/gobi-web-integration v6.14.20

Weekly downloads
1,110
License
Apache-2.0
Repository
bitbucket
Last release
14 days ago

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>

If you would like to configure titles or thumbnail urls per story, then you can add them as child elements:

<div
  class="gobi-stories"
  data-gobi-kebab-cased-option="value"
  data-gobi-some-other-kebab-cased-option="value"
>
  <div data-gobi-story="story-id" data-gobi-title="About Us"></div>
  <div
    data-gobi-story="another-story-id"
    data-gobi-title="Our Product"
    data-gobi-thumbnail-url="..."
  ></div>
</div>

Note that you can add new lines to title by using a new line in the HTML, or by adding \n with the title itself.

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. See Bubble Options for more information:

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

optiondefaultdescription
container#gobi-hereRequired for inline javascript. String. Query Selector for HTMLElement. Container where the module will be embed.
color#15d6eaAny valid css color value (#000, rgb(...), rgba(...)). The color of the border around the story bubble.
bubbleSize96pxValid css size value, except % (10px, 10vw...). The size of the avatar aka bubble.
hideTitlefalseBoolean. Hides the bubble title if true (default false)
animatedBubblefalseBoolean. Makes the bubbles as gif animation.
wrapfalseBoolean. Add styles which allow a horizontal series of bubbles to wrap to new lines, when the screen is narrow.
isFullHeightMobiletrueBoolean. Add styles which allow making a full-screen popup. It's work only on mobile phone
showPlayIconfalseBoolean. Add Play icon inside the bubbles
playIconUrlundefinedOptional string, will show the given icon in the play bubble.
aligncenterString. Valid values 'left', 'right', 'end', 'start', 'center' . It sets alignment for bubbles horizontally
autoSeguefalseBoolean. Enable or disable the transition to next story in the end
fullscreenPlayerfalseBoolean. Set to true to remove all margins from the player when opened in popup mode
noShadefalseBoolean. Set to true to not apply a page background shade when the player is opened in popup mode
titleFontSize12pxValid css size value. By default, a size is selected based on bubbleSize between 12px and 36px.
titleFontColorblackAny valid css color value (#000, rgb(...), rgba(...)). The color of the bubble title text.
titleFontFamilyundefinedValid css font family name. Inherited from the document by default.
titleFontWeightundefinedValid css font weight. Inherited from the document by default.
inheritTextFontFamilyfalseBoolean. Whether to inherit the font family from the page for bubble titles.
inheritTextStylesfalseBoolean. Whether to inherit font family, font size, font weight and color from the page for bubble titles.
zIndex2000000Number. Sets the priority of the player above other content when open.
on.loadedfunctionFunction. Called when all Bubbles have loaded.
on.closefunctionFunction. Called when all popups are closed.
stories[]Required for inline javascript. Array. Data of stories.
stories0...n.idRequired. String. Identifire of story.
stories0...n.titleString. Change title text of specific story.
stories0...n.thumbnailUrlString. Overrides the image used for the bubble.
stories0...n.bubbleSrcDeprecated. Alias of thumbnailUrl.
playerOptions{}Object. Provides options to the player when opening. See Player Options for details.

Events

on.loaded is called with a controller as it's first parameter. See Opening Stories Programmatically for more information.

Embedded player

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

Player Options

optiondefaultdescription
containerQuery Selector for HTMLElement. Container where the player will be inserted.
storyIdRequired. String. The key of the story.
autoStartfalseBoolean. Add autoplay attributes to the video.
autoStartWithSoundfalseBoolean. Add autoplay attributes to the video, and don't mute the video at the same time.
loopfalseBoolean. Add loop function to video.
roundedCornerstrueBoolean. Enable or disable rounded corners to player element.
shadowtrueBoolean. Enable or disable shadow on the player element.
width612Number. Set player width. If height is not defined it will calculate automaticaly using an aspect ratio of 16:9.
height1088Number. Set player height. If width is not defined it will calculate automaticaly using an aspect ratio of 16:9.
checkViewPorttrueBoolean. Enable functionality which pause player if it outside of screen view area.
playButtontrueBoolean. Enable or disable play button.
transcriptButtontrueBoolean. Enable or disable button to download a transcript. Only shown if applicable.
savePositiontrueBoolean. Enable or disable save last watched chapter. It needs to confirm policy by user
useMediaProxyfalseBoolean. Enable the use of a reverse proxy hosted by Gobi for media content.
on[]Array. Data of event listener
on.videoPlayfunctionCalled when the video plays.
on.videoPausefunctionCalled when the video pauses.
on.videoCompletefunctionCalled when the video completes.
on.clickPreviousfunctionCalled when changing to the previous chapter.
on.clickNextfunctionCalled when changing to the next chapter.
on.clipChangefunctionCalled when a chapter changes.
on.newIterationfunctionCalled when the story loops back to the beginning (requires loop to be true).
on.errorfunctionCalled when an error occurs.
on.loadedfunctionCalled 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();

Opening Gobi Stories Programmatically

Several functions allow you to open story popups programmatically, either immediately or using a controller passed to a callback:

FunctionDescription
openPopup(id, options)Opens a story immediately without preloading
renderPopups(options, callback)Preloads stories for opening later
renderBubbles(options, callback)Displays bubbles that can be opened later
discover(options, callback)Finds and renders gobi-stories embeds

Options are the same as Bubble Options.

The functions renderPopups() and renderBubbles() require a container to be specified in options. The discover() function required elements in the dom with the class gobi-stories to create bubbles or gobi-popups to create popups.

The function openPopup() does not require an element to be provided.

The callback's only argument is a controller with the properties:

PropertyTypeDescription
storyIdsstring[]An array of loaded story ids
openPopup(id)functionOpens a popup story player for the given story id

Note: The on.loaded bubble option is also passed a controller as it's first argument.

You can open a popup story player at any time with openPopup():

gobi.openPopup('story-id');

Important: In many browsers playing a video with sound requires at least one user interaction that starts a video with sound. Therefore openPopup() must either be called by a user interaction event (such as click), or after this requirement has been met some other way, otherwise the video may fail to start.

To preload story data and poster images before opening a popup, call renderPopups() and use the controller passed to the callback to open the story. This may provide a smoother experience, particularly on slower internet connections.

gobi.renderPopups({ stories: [{ id: 'story-id' }] }, controller => {
  controller.openPopup('story-id');
});

If you want to show bubbles on your page and want to open them programmatically, you can use renderBubbles to create the bubbles and get the controller with a callback:

gobi.renderBubbles(
  { container: '#gobi-container', stories: [{ id: 'story-id' }] },
  controller => {
    controller.openPopup('story-id');
  }
);

If you are using gobi.discover() to create your bubbles, you can get a controller using the second parameter, and use it later:

let gobiController;

gobi.discover({}, controller => {
  gobiController = controller;
});

// You can now use gobiController to open stories, for example with onClick handlers.

Gobi Stories Public API

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

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

ParameterTypeDescription
:viewKeystringThe 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;
  coverUrl: string;
  webmCoverUrl?: string;
  mp4CoverUrl?: 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;
}
6.14.20

14 days ago

6.14.19

22 days ago

6.14.18

1 month ago

6.14.17

2 months ago

6.14.16

2 months ago

6.14.15

2 months ago

6.14.14

2 months ago

6.14.13

3 months ago

6.14.11

5 months ago

6.14.10

6 months ago

6.14.6

7 months ago

6.14.5

9 months ago

6.14.9

7 months ago

6.14.8

7 months ago

6.14.7

7 months ago

6.14.1-beta

11 months ago

6.14.4

10 months ago

6.14.3

10 months ago

6.14.0-b

11 months ago

6.14.2

11 months ago

6.14.1

11 months ago

6.14.0

12 months ago

6.13.20

1 year ago

6.13.19

1 year ago

6.13.17

1 year ago

6.13.18

1 year ago

6.13.13

1 year ago

6.13.14

1 year ago

6.13.15

1 year ago

6.13.16

1 year ago

6.13.11

2 years ago

6.13.12

2 years ago

6.13.9

2 years ago

6.13.10

2 years ago

6.13.7

2 years ago

6.13.8

2 years ago

0.0.1

2 years ago

0.0.3

2 years ago

0.0.2

2 years ago

0.0.4

2 years ago

6.13.6

2 years ago

6.13.5

2 years ago

6.13.4

2 years ago

6.13.3

2 years ago

6.13.2

2 years ago

6.13.1

2 years ago

6.13.0

2 years ago

6.12.4

2 years ago

6.12.3

2 years ago

6.12.2

2 years ago

6.12.1

3 years ago

6.12.0

3 years ago

6.11.6

3 years ago

6.11.5

3 years ago

6.11.4

3 years ago

6.11.3

3 years ago

6.11.1

3 years ago

6.11.0

3 years ago

6.11.2

3 years ago

6.10.0

3 years ago

6.9.23

3 years ago

6.9.22

3 years ago

6.9.21

3 years ago

6.9.20

3 years ago

6.9.19

3 years ago

6.9.18

3 years ago

6.9.17

3 years ago

6.9.16

3 years ago

6.9.15

3 years ago

6.9.14

3 years ago

6.9.13

3 years ago

6.9.12

3 years ago

6.9.11

3 years ago

6.9.10

3 years ago

6.9.9

3 years ago

6.9.8

3 years ago

6.9.6

3 years ago

6.9.5

3 years ago

6.9.4

3 years ago

6.9.3

3 years ago

6.9.2

3 years ago

6.9.1

3 years ago

6.8.3

3 years ago

6.9.0

3 years ago

6.8.0

3 years ago

6.8.2

3 years ago

6.7.16

3 years ago

6.7.15

3 years ago

6.7.14

3 years ago

6.7.12

3 years ago

6.7.13

3 years ago

6.7.11

3 years ago

6.7.10

3 years ago

6.7.9

4 years ago

6.7.8

4 years ago

6.7.7

4 years ago

6.7.5

4 years ago

6.7.2

4 years ago

6.7.1

4 years ago

6.7.4

4 years ago

6.7.3

4 years ago

6.6.9

4 years ago

6.7.0

4 years ago

6.6.8

4 years ago

6.6.7

4 years ago

6.6.6

4 years ago

6.6.5

4 years ago

6.6.4

4 years ago

6.6.3

4 years ago

6.6.2

4 years ago

6.6.1

4 years ago

6.6.0

4 years ago

6.5.1

4 years ago

6.5.0

4 years ago

6.4.3

4 years ago

6.4.2

4 years ago

6.4.1

4 years ago

6.4.0

4 years ago

6.3.2

4 years ago

6.3.1

4 years ago

6.2.0

4 years ago

6.3.0

4 years ago

6.1.0

4 years ago

6.1.2

4 years ago

6.1.1

4 years ago

6.1.4

4 years ago

6.1.3

4 years ago

6.0.9

4 years ago

6.0.8

4 years ago

6.1.6

4 years ago

6.1.5

4 years ago

6.0.7

4 years ago

6.0.6

4 years ago

6.0.5

4 years ago

6.0.3

4 years ago

6.0.4

4 years ago

6.0.2

4 years ago

6.0.1

4 years ago

6.0.0

4 years ago

5.1.5

4 years ago

5.1.4

4 years ago

5.1.1

4 years ago

5.1.0

4 years ago

5.0.3

4 years ago

5.0.2

4 years ago

5.0.1

4 years ago

5.0.0

4 years ago

4.7.1

4 years ago

4.7.0

4 years ago

4.6.3

4 years ago

4.6.2

4 years ago

4.6.1

4 years ago

4.6.0

4 years ago

4.5.2

4 years ago

4.5.1

4 years ago

4.5.0

4 years ago

4.4.1

4 years ago

4.4.0

4 years ago

4.3.0

4 years ago

4.2.1

4 years ago

4.2.0

4 years ago

4.1.2

5 years ago

4.1.1

5 years ago

4.1.0

5 years ago

4.0.5

5 years ago

4.0.4

5 years ago

4.0.3

5 years ago

4.0.2

5 years ago

4.0.1

5 years ago

4.0.0

5 years ago

3.10.1

5 years ago

3.10.0

5 years ago

3.9.9

5 years ago

3.9.8

5 years ago

3.9.7

5 years ago

3.9.6

5 years ago

3.9.5

5 years ago

3.9.4

5 years ago

3.9.3

5 years ago

3.9.2

5 years ago

3.9.1

5 years ago

3.9.0

5 years ago

3.8.0

5 years ago

3.7.0

5 years ago

3.6.0

5 years ago

3.5.0

5 years ago

3.4.0

5 years ago

3.3.0

5 years ago

3.2.0

5 years ago

3.1.0

5 years ago

3.0.0

5 years ago

2.2.1

5 years ago

2.2.0

5 years ago

2.1.0

5 years ago

2.0.8

5 years ago

2.0.7

5 years ago

2.0.6

5 years ago

2.0.5

5 years ago

2.0.4

5 years ago

2.0.3

5 years ago

2.0.2

5 years ago

2.0.1

5 years ago

2.0.0

5 years ago

1.7.4

5 years ago

1.7.3

5 years ago

1.7.2

5 years ago

1.7.1

5 years ago

1.7.0

5 years ago

1.6.5

5 years ago

1.6.4

5 years ago

1.6.3

5 years ago

1.6.2

5 years ago

1.6.1

5 years ago

1.6.0

5 years ago

1.5.1

5 years ago

1.4.2

5 years ago

1.4.1

5 years ago

1.4.0

5 years ago

1.3.0

5 years ago

1.2.4

5 years ago

1.2.3

5 years ago

1.2.2

5 years ago

1.2.1

5 years ago

1.1.3

5 years ago

1.1.2

5 years ago

1.1.1

5 years ago

1.1.0

5 years ago

1.0.4

5 years ago

1.0.3

5 years ago

1.0.2

5 years ago

1.0.1

5 years ago

1.0.0

5 years ago