storyshaker-sdk

SDK for Storyshaker API

Storyshaker SDK

SDK which provides basic tools for developers to operate with public methods of Storyshaker API (private methods are not included here).

Installation

npm install storyshaker-sdk --save

Getting Started

The easiest way to start working with Storyshaker SDK is to include its compiled and minified version into your code. Place the following <script> into <head> section of your page.

<script src="dist/storyshakersdk.min.js"></script>

Then class(function) StoryshakerSDK become available to you. Its usage with examples is described further.

Or you can import it in your project as module.

import StoryshakerSDK from '/path/to/sdk';

Methods, settings and specific options for each method

new StoryshakerSDK(settings)

  • settings[Object]: settings for SDK instance which should include newsroom token and some other additional settings, for instance, to oparate with storage in browser, etc
var sdk = new StoryshakerSDK({
  isCacheEnabled: false,
  token: '1572h1m4xmg43',
});

Settings

Name Default Required Description
token - yes token of newsroom for which embed/s and walls will be fetched
host https://api.newsroom.co no Host name for server API requests
isCacheEnabled true no If enabled then all fetched data will be stored in storage of browser (session storage). On second and further requests for this data they will be taken from store and return to user without API server requests
storageName 'storyshakerSdk' no Name of property in storage where all SDK data will be stored

Methods

Name Description
clearStorage() Force to delete all saved data in session storage
getDefaultSettings() Return default settings (default values for isCacheEnabled and backgroundReload for now)
getEmbeds(options) Returns a list of embeds of newsroom, options is optional
getEmbed(id, options) Returns specific embed of newsroom by id (string)
id is required, options is optional
getWalls(paramsStr, options) Look at the description below getWalls method details. paramsStr is required, options is optional
getWallsSearch(paramsStr, query, options) Reveals the search results of the social wall entries of newsroom. paramsStr is the same as for getWalls method. Please refer to this method to get more detailed description of it. Results are based on query (string) provided by user

Not required parameter options which can be passed as last argument almost in every method allows to use individual settings for this method. Actually it redefines some common settings used during creation of SDK instance but only for this specific execution.

getWalls method details

Returns object with -wallList- property which stores a list of the newest social wall entries of newsroom. Type of returned value is an Object. It can have next methods to work with data.

Parameters for request

paramsStr string of method can has next properties which then will be passed to the request as parameters:

Name Required Description
type (string) no Can take next values: "post" (except twitter social posts), "story", "post,story" or "!story" (which in turn gives ability to return all social posts included twitter). It depends on what type of items does user want to get: posts, stories or both. If it not specified then all types of items have been returned.
count (number) no It determines number of items returned from server (default is 20)
tag (string) no Can take next values: "pin", "top", "top,pin", "!pin", "!top" which indicates what kind of stories shoule be returned: only pinned, only marked as top, only top and pinned stories, all stories excep pinned, all except top

Methods of response object

Name Description
getNewer() Retrieve next set of items with the same params as were used for fetching current array of items
getOlder() Retrieve previous set of items with the same params as were used for fetching current array of items
hasNewer() Returns boolean value which indicates wether walls have newer posts or not
hasOlder() Returns boolean value which indicates wether walls have older posts or not

Properties of response object

Name Description
wallList Stores list of the social wall entries of newsroom

Each object in the -wallList- array has method like() which serves for like action for this specific post.

Example

var walls;
var newest;
var oldest;
// Fetch 10 stories by token
sdk.getWalls('story', 10).then(function(response) {
  walls = response;
});
...
...
// Fetch next 10 stories of walls array
walls.getNewer().then(function(response) {
  newest = response;
});
...
...
// Fetch previous 10 stories of newest array
newest.getOlder().then(function(response) {
  oldest = response;
});

Options

Specific options which can be passed as last argument to each method for its customization. Optional parameter.

Name Type Description
forceReload Boolean Force to send request to the server each time despite the cache is enabled or not

Examples of methods usage:

// Remove data from session storage
sdk.clearStorage();
// Fetch settings for specific embed of specific newsroom
sdk.getEmbed('wb-fS5be2a7ad52b42I'); 

Examples of fetched data for some methods you can see in Storyshaker API doc.

Guide for developing and expanding of Storyshaker SDK

Requirements

Installation

  • git clone this repository
  • npm install (to install npm dependencies)

Running

  • npm start (to start the development server)
  • npm run build (to build es6+ code into es2015 for those browsers which are not supporting new js features)
  • npm run build:lib (to build minified library file which can be used inside non-module Applications or services)
  • npm run preview (to preview the production build)

Publish

Development is done on the develop branch. To publish a new release version, execute npm version major | minor | patch, and merge develop into master. The bitbucket build pipeline will build and publish the new version to the npm repository.

Repository


相关推荐