@gobistories/gobi-web-integration
Version:
This library will let you put your Gobi stories on your site.
512 lines (489 loc) • 16.2 kB
HTML
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Gobi Web Integration Readme</title>
<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-core.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/plugins/autoloader/prism-autoloader.min.js"></script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism.min.css">
<base target="_parent">
<script>
window.addEventListener('load', function () {
window.top.postMessage({
height: document.body.scrollHeight,
}, "*");
});
</script>
<style>
html {
font-size: 16px;
}
body {
font-family: Nunito, sans-serif;
font-size: 0.875rem;
color: #001c38;
}
h1,
h2,
h3,
h4,
h5,
h6 {
margin-top: 20px;
margin-bottom: 10px;
font-family: 'Lineto circular pro', sans-serif;
}
h1 {
font-size: 38px;
line-height: 44px;
font-weight: 700;
}
h2 {
font-size: 32px;
line-height: 36px;
font-weight: 700;
}
a {
color: #2ba6fc;
text-decoration: none;
}
tr {
text-align: left;
}
td,
th {
padding: 7px;
border: 1px solid #001c3817;
}
td code {
white-space: nowrap;
}
pre {
width: min-content;
border-radius: 5px;
}
@font-face {
font-family: 'Nunito';
src: url('https://uploads-ssl.webflow.com/606f59e162caa70af6365471/606f6512884094dadc4ee18f_Nunito-ExtraBold.ttf') format('truetype');
font-weight: 800;
font-style: normal;
font-display: swap;
}
@font-face {
font-family: 'Nunito';
src: url('https://uploads-ssl.webflow.com/606f59e162caa70af6365471/606f65122db596ff7b467fba_Nunito-Black.ttf') format('truetype');
font-weight: 900;
font-style: normal;
font-display: swap;
}
@font-face {
font-family: 'Nunito';
src: url('https://uploads-ssl.webflow.com/606f59e162caa70af6365471/606f65128840943d9e4ee18e_Nunito-Bold.ttf') format('truetype');
font-weight: 700;
font-style: normal;
font-display: swap;
}
@font-face {
font-family: 'Nunito';
src: url('https://uploads-ssl.webflow.com/606f59e162caa70af6365471/606f6512ad2674216cdb2e7e_Nunito-Regular.ttf') format('truetype');
font-weight: 400;
font-style: normal;
font-display: swap;
}
@font-face {
font-family: 'Nunito';
src: url('https://uploads-ssl.webflow.com/606f59e162caa70af6365471/606f65122db5963587467fbb_Nunito-ExtraLight.ttf') format('truetype');
font-weight: 200;
font-style: normal;
font-display: swap;
}
@font-face {
font-family: 'Nunito';
src: url('https://uploads-ssl.webflow.com/606f59e162caa70af6365471/606f65126543e443255c9e16_Nunito-SemiBold.ttf') format('truetype');
font-weight: 600;
font-style: normal;
font-display: swap;
}
@font-face {
font-family: 'Nunito';
src: url('https://uploads-ssl.webflow.com/606f59e162caa70af6365471/606f65120a9f8b91984d4f31_Nunito-Light.ttf') format('truetype');
font-weight: 300;
font-style: normal;
font-display: swap;
}
@font-face {
font-family: 'Gt super display';
src: url('https://uploads-ssl.webflow.com/606f59e162caa70af6365471/606f65517d1c1d3d934e2cfc_GT-Super-Display-Light.ttf') format('truetype');
font-weight: 300;
font-style: normal;
font-display: swap;
}
@font-face {
font-family: 'Gt super display';
src: url('https://uploads-ssl.webflow.com/606f59e162caa70af6365471/606f6551d077567eed26663f_GT-Super-Display-Bold.ttf') format('truetype');
font-weight: 700;
font-style: normal;
font-display: swap;
}
@font-face {
font-family: 'Lineto circular pro';
src: url('https://uploads-ssl.webflow.com/606f59e162caa70af6365471/6078727daa14d4f169dfec0e_lineto-circular-pro-book.ttf') format('truetype');
font-weight: 400;
font-style: normal;
font-display: swap;
}
@font-face {
font-family: 'Lineto circular pro';
src: url('https://uploads-ssl.webflow.com/606f59e162caa70af6365471/6078727d16c3356c325cce38_lineto-circular-pro-bold.ttf') format('truetype');
font-weight: 700;
font-style: normal;
font-display: swap;
}
</style>
</head>
<body>
<div>
<h1 id="gobi-stories-api-documentation">Gobi Stories API Documentation</h1>
<h2 id="overview">Overview</h2>
<p>The Gobi API allows you to integrate Collections and Stories into your Content Management System (CMS), Applicant Tracking System (ATS), or other content systems. This API provides access to Teams, Collections, and Stories, which you can use to populate options in your content management system.</p>
<p>The API responses provide information for you to populate your UI with relevant labels and values, render previews of Collections or Stories using our embed script, or create your own custom thumbnails for richer user interfaces.</p>
<h2 id="security">Security</h2>
<p>The API uses an API key for authentication. Please note the following security considerations:</p>
<ul>
<li>Use the API key only for server-side requests or on pages where the user is authenticated and has permission to access the resources.</li>
<li>The API key grants access to all endpoints for a single organization within Gobi.</li>
<li>Never expose your API key in client-side code or public repositories.</li>
</ul>
<h2 id="base-url">Base URL</h2>
<p>All API requests should be made to:</p>
<pre><code>https://api.gobistories.com/access/v1</code></pre>
<h2 id="authentication">Authentication</h2>
<p>To authenticate your requests, you need to include your API key in the Authorization header as a Bearer token. Here's how to format the header:</p>
<pre><code>Authorization: Bearer YOUR_API_KEY</code></pre>
<p>Replace <code>YOUR_API_KEY</code> with your actual API key.</p>
<p>Example using cURL:</p>
<pre><code class="bash language-bash">curl -H "Authorization: Bearer YOUR_API_KEY" https://api.gobistories.com/access/v1/teams</code></pre>
<p>Make sure to include this header in all your API requests to authenticate them properly.</p>
<h2 id="using-the-gobi-sdk">Using the Gobi SDK</h2>
<p>If you have loaded our Gobi Web Integration script, you can use the Gobi SDK to interact with the API easily. Here's how to use it:</p>
<h3 id="initializing-the-api-client">Initializing the API Client</h3>
<p>To create an API client instance, use the <code>gobi.api()</code> method with your API key:</p>
<pre><code class="typescript language-typescript">const api = gobi.api(apiKey);</code></pre>
<h3 id="fetching-data">Fetching Data</h3>
<p>Once you have an API client instance, you can use the following methods to fetch data:</p>
<h4 id="get-all-teams">Get All Teams</h4>
<pre><code class="typescript language-typescript">const teams = await api.teams();</code></pre>
<h4 id="get-all-collections">Get All Collections</h4>
<pre><code class="typescript language-typescript">const collections = await api.collections();</code></pre>
<h4 id="get-all-stories">Get All Stories</h4>
<pre><code class="typescript language-typescript">const stories = await api.stories();</code></pre>
<h4 id="get-collections-for-a-specific-team">Get Collections for a Specific Team</h4>
<pre><code class="typescript language-typescript">const collections = await api.collections(teamId);</code></pre>
<h4 id="get-stories-for-a-specific-team">Get Stories for a Specific Team</h4>
<pre><code class="typescript language-typescript">const stories = await api.stories(teamId);</code></pre>
<h3 id="shorthand-for-collections-and-stories">Shorthand for Collections and Stories</h3>
<p>If you just need all Collections or Stories for the account, you can use these shorthand methods:</p>
<pre><code class="typescript language-typescript">const collections = await gobi.api(apiKey).collections();
const stories = await gobi.api(apiKey).stories();</code></pre>
<h3 id="error-handling">Error Handling</h3>
<p>The SDK methods will throw a <code>GobiApiException</code> if there's an API error or network issue. Make sure to wrap your calls in a try-catch block:</p>
<pre><code class="typescript language-typescript">try {
const collections = await api.collections();
// ... process the collections
} catch (error) {
if (error instanceof GobiApiException) {
console.error(`API Error (${error.statusCode}): ${error.message}`);
} else {
console.error('An unexpected error occurred:', error);
}
}</code></pre>
<h2 id="endpoints">Endpoints</h2>
<h3 id="1-get-teams">1. Get Teams</h3>
<p>Retrieves all Teams. You can use Teams to filter Collections and Stories.</p>
<ul>
<li><strong>HTTP Method</strong>: GET</li>
<li><strong>Endpoint</strong>: <code>/teams</code></li>
</ul>
<h4 id="request">Request</h4>
<p>This endpoint doesn't require any parameters.</p>
<h4 id="response">Response</h4>
<table>
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>id</td>
<td>string</td>
<td>Identifier for the Team</td>
</tr>
<tr>
<td>name</td>
<td>string</td>
<td>Name of the Team</td>
</tr>
<tr>
<td>organizationId</td>
<td>string</td>
<td>Identifier for the Organization</td>
</tr>
</tbody>
</table>
<p>Example Response:</p>
<pre><code class="json language-json">[
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "Marketing Team",
"organizationId": "123e4567-e89b-12d3-a456-426614174001"
},
{
"id": "123e4567-e89b-12d3-a456-426614174002",
"name": "Sales Team",
"organizationId": "123e4567-e89b-12d3-a456-426614174001"
}
]</code></pre>
<h3 id="2-get-collections">2. Get Collections</h3>
<p>Retrieves all Collections, or all Collections for a specified Team, ordered by title.</p>
<ul>
<li><strong>HTTP Method</strong>: GET</li>
<li><strong>Endpoint</strong>: <code>/collections</code></li>
</ul>
<h4 id="request-1">Request</h4>
<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>teamId</td>
<td>string</td>
<td>No</td>
<td>Identifier for the Team to filter Collections</td>
</tr>
</tbody>
</table>
<h4 id="response-1">Response</h4>
<table>
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>id</td>
<td>string</td>
<td>Identifier for the Collection</td>
</tr>
<tr>
<td>teamId</td>
<td>string</td>
<td>ID of the Team that the Collection belongs to</td>
</tr>
<tr>
<td>organizationId</td>
<td>string</td>
<td>Identifier of the Organization</td>
</tr>
<tr>
<td>tag</td>
<td>string</td>
<td>Value that can be used with a teamId to load a Collection instead of using the collectionId</td>
</tr>
<tr>
<td>title</td>
<td>string</td>
<td>Title of the Collection</td>
</tr>
<tr>
<td>embedType</td>
<td>string</td>
<td>Type of embed for the Collection ("bubbles" or "cards")</td>
</tr>
<tr>
<td>storyIds</td>
<td>string[]</td>
<td>Array of Story IDs included in the Collection</td>
</tr>
<tr>
<td>createdAt</td>
<td>number</td>
<td>UNIX timestamp (in seconds) of when the Collection was created</td>
</tr>
<tr>
<td>publishedAt</td>
<td>number</td>
<td>UNIX timestamp (in seconds) of when the Collection was published</td>
</tr>
</tbody>
</table>
<p>Example Response:</p>
<pre><code class="json language-json">[
{
"id": "123e4567-e89b-12d3-a456-426614174003",
"teamId": "123e4567-e89b-12d3-a456-426614174000",
"organizationId": "123e4567-e89b-12d3-a456-426614174001",
"tag": "summer-campaign",
"title": "Summer Campaign Collection",
"embedType": "bubbles",
"storyIds": ["story1", "story2", "story3"],
"createdAt": 1633027200,
"publishedAt": 1633113600
}
]</code></pre>
<h3 id="3-get-stories">3. Get Stories</h3>
<p>Retrieves all stories, or all stories for a specified Team, ordered by title.</p>
<ul>
<li><strong>HTTP Method</strong>: GET</li>
<li><strong>Endpoint</strong>: <code>/stories</code></li>
</ul>
<h4 id="request-2">Request</h4>
<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>teamId</td>
<td>string</td>
<td>No</td>
<td>Identifier for the Team to filter stories</td>
</tr>
</tbody>
</table>
<h4 id="response-2">Response</h4>
<table>
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>id</td>
<td>string</td>
<td>Unique identifier for the story (5 character alphanumeric string)</td>
</tr>
<tr>
<td>teamId</td>
<td>string</td>
<td>Identifier for the Team that the Story belongs to</td>
</tr>
<tr>
<td>organizationId</td>
<td>string</td>
<td>Identifier for the Organization</td>
</tr>
<tr>
<td>title</td>
<td>string</td>
<td>Title of the story as shown in Studio</td>
</tr>
<tr>
<td>displayTitle</td>
<td>string</td>
<td>Display Title of the story as shown in embeds (will be the same as title if not set)</td>
</tr>
<tr>
<td>thumbnailUrl</td>
<td>string</td>
<td>URL for a small square image thumbnail (typically used to show a bubble style thumbnail)</td>
</tr>
<tr>
<td>webmThumbnailUrl</td>
<td>string</td>
<td>WebM format URL for the thumbnail video</td>
</tr>
<tr>
<td>mp4ThumbnailUrl</td>
<td>string</td>
<td>MP4 format URL for the thumbnail video</td>
</tr>
<tr>
<td>coverUrl</td>
<td>string</td>
<td>URL for a portrait thumbnail (typically used to show a card style thumbnail)</td>
</tr>
<tr>
<td>webmCoverUrl</td>
<td>string</td>
<td>WebM format URL for the cover video</td>
</tr>
<tr>
<td>mp4CoverUrl</td>
<td>string</td>
<td>MP4 format URL for the cover video</td>
</tr>
<tr>
<td>posterUrl</td>
<td>string</td>
<td>URL for the first frame of the Story video (typically as a placeholder for the Story Player before it starts playing)</td>
</tr>
<tr>
<td>watchUrl</td>
<td>string</td>
<td>URL to watch the story on player.gobistories.com</td>
</tr>
<tr>
<td>createdAt</td>
<td>number</td>
<td>UNIX timestamp (in seconds) of when the Story was created</td>
</tr>
<tr>
<td>publishedAt</td>
<td>number</td>
<td>UNIX timestamp (in seconds) of when the Story was published</td>
</tr>
</tbody>
</table>
<p>Example Response:</p>
<pre><code class="json language-json">[
{
"id": "pg8bz",
"teamId": "123e4567-e89b-12d3-a456-426614174000",
"organizationId": "123e4567-e89b-12d3-a456-426614174001",
"title": "New Product Launch",
"thumbnailUrl": ".../thumbnail/pg8bz.jpg",
"webmThumbnailUrl": ".../thumbnail/pg8bz.webm",
"mp4ThumbnailUrl": ".../thumbnail/pg8bz.mp4",
"coverUrl": ".../cover/pg8bz.jpg",
"webmCoverUrl": ".../cover/pg8bz.webm",
"mp4CoverUrl": ".../cover/pg8bz.mp4",
"posterUrl": ".../poster/pg8bz.jpg",
"watchUrl": "https://player.gobistories.com/demo01",
"createdAt": 1633027200,
"publishedAt": 1633113600
}
]</code></pre>
<h2 id="usage-notes">Usage Notes</h2>
<ul>
<li>You can use the <code>tag</code> field in collections with a <code>teamId</code> to load a Collection instead of using the collection id. This is useful in a CMS or ATS where a collection is made for a particular content section or category and you match the tag to a section id.</li>
<li>The <code>embedType</code> field indicates how a Collection will be displayed when embedded (either as "bubbles" or "cards").</li>
<li>All timestamp fields (<code>createdAt</code> and <code>publishedAt</code>) are in UNIX timestamp format (seconds since epoch).</li>
<li>The various URL fields provide different options for thumbnails and previews:</li>
<li><code>thumbnailUrl</code>, <code>webmThumbnailUrl</code>, and <code>mp4ThumbnailUrl</code> are for small square images typically shown as circles for 'bubbles'.</li>
<li><code>coverUrl</code>, <code>webmCoverUrl</code>, and <code>mp4CoverUrl</code> are for portrait thumbnails usually used to show 'cards'.</li>
<li><code>posterUrl</code> is always an image of the first frame of the Story video.</li>
<li>The base URL for thumbnail and cover images is not fixed and should not be hardcoded in your application. Always use the full URLs provided in the API responses.</li>
</ul>
</div>
</body>
</html>