storyshaker-sdk
v0.2.7
Published
SDK for Storyshaker API
Downloads
8
Maintainers
newsroom-developerReadme
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 --saveGetting 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
- Node > 7.6
Installation
git clonethis repositorynpm 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.