Ayuda en lnea

1. Overview
1. 1. Overview

2. Plugins Documentation
2. 1. Plugins Overview
2. 1. 1. Custom sections overview
GoodBarber allows you to create your own sections, using HTML5.
There are 2 types of custom sections, with 2 levels of complexity:

Basic custom sections (low complexity, and limited possibilities)

HTML5 Plugins Sections (coding required, high customisation possibilities)

1. Basic custom sections

The Custom section is a section using HTML to allow you to display rich, static content. It's cached into the app, which
means that it's available when there's no connection.
You can use pre-definied templates to manage your custom section, or directly modify its HTML code. It is possible to
display dynamic or distant contents, using the HTTP template, hosted on your server.
Usage (example) : display a presentation page, give some contact informations
Complexity : Low
Interactions with the rest of the app : Basic
Quality : Good

2. HTML5 Plugins Sections

The HTML5 Plugins sections are sections that can contain your own source code, specifically developed for
GoodBarber. The Plugin development need an expertise in HTML/JavaScript, and a strong knowledge of the
specifications. A good knowledge of the mobile development practices will help you.
The HTML5 Plugins sections will allow you to enrich your app with features regarding your specific needs.
Usage (example) : develop your own section based on a custom data source, integrate a quizz or a survey, etc.
Complexity : High (web skills + mobile + knowledge of GoodBarber)
Interactions with the rest of the app : High
Quality: Native-like

3. Some advices
When you think about integrate a customized section into your app, think about the features and the level of
customization that you will need.
The HTML5 plugins will allow you to enrich you app, but will be more complex to develop than a basic Custom section. It
will also need to be maintained along the life of your app.
Always keep it simple!

2. 1. 2. HTML5 Plugins Overview

1. Plugin overview
An HTML5 plugin for GoodBarber is a bundle of HTML/Javascript files, and several assets which will be cached into the
app and executed directly in your app.
An HTML5 plugin section will appear as the other sections in your app:
- It will be displayed between the Navigation Bar and the bottom of the screen, or the TabBar, according to the
navigation mode you choosed
- By delegating its internal navigation to the app, the plugin will benefit of the same transition effects (horizontal push,
modal) than the other sections
- By delegating its cache management and its network interactions, the plugin will be available offline
- It will also have the capability to interact with the rest of the app (send and receive messages)

2. Content of the plugin bundle

Your plugin can contain several types of files:
- An index.html file (mandatory) that will be the plugin's main page
- Other HTML files (optionnal) that would be the plugin's other pages
- Other resource files (optionnal), like images, CSS stylesheets, JS librairies, etc.

All the dependancies to the plugin files have to be made in the current directory (./).

3. How to send and receive message to and from the app

There are two types of interactions possible between your plugin and your GoodBarber app.
Messages sent by the plugin to the app (Plugin => Native)
The plugin can send messages to the app, by starting a navigation to documented URL schemes. These methods can
be used to manage the internal or external navigation of the plugin, to manage the network interactions, and other
methods.
Messages sent by the app to the plugin (Native => Plugin)
These are JavaScript methods sent by the app on the plugin. It can be callbacks sent in response to methods called by
the plugin, or methods called by the app according to the lifecycle of the app. The plugin has to implement the
JavaScript methods of the callback protocol that it needs to handle.
The implementation process of the methods and callbacks of the GoodBarber Plugin API is described in the
article Plugin API Overview.

4. GoodBarber JavaScript ToolKit

The methods available to discuss with the app (navigation, download, etc.) can be called directly by sending HTTP
request to the app.
However, in most cases, you may prefer to use the GoodBarber JavaScript ToolKit that makes the calls easier, with an
encapsulation of the requests into JavaScript functions.
In this documentation, you'll find the method prototypes in the HTTP requests version, and their equivalent in
GBJSToolKit.

2. 2. Plugin API Documentation

2. 2. 1. Plugin API Overview (Methods & Callbacks)
The GoodBarber Plugin API allows you to directly utilize the available interaction methods with the application.

1. Exchange Principle Plugin => Native => Plugin

The method calls from the plugin to the application are made by triggering a web navigation to a particular URL.
The callbacks are performed through JavaScript method calls to the plugin.

2. Method Cals (Plugin => Native)

All method calls of the GoodBarber API Plugin must be performed by triggering a web navigation. This navigation may
be triggered in several ways:
- Clicking on a link
- Calling a document.location () in JavaScript
- Submitting a form
Please note: Ajax requests (XMLHttpRequest) are not considered as triggering a navigation and can therefore not be
used for method calls of the GoodBarber Plugin API.
The majority of available methods (apart from the "basic" methods described in the documentation) must trigger a
navigation to a URL beginning with goodbarber://, followed by the name of the method to call and other parameters.
With a few exceptions, the arguments muss go directly through the URL, but in some instance, especially for navigation
methods, POST arguments may be used.
Pour dclencher simplement des requtes POST depuis du code JavaScript, utilisez la mthode gbPostRequest
votre disposition dans le [GoodBarber JavaScript ToolKit]url: .
To trigger POST requests from the JavaScript code, use the gbPostRequest method in the GoodBarber JavaScript
ToolKit.

3. Calls and implementation of callbacks (Native => Plugin)

Callbacks are prototypes of JavaScript functions to be implemented in your code. It is very important to respect all
specifications so that the information is exchanged correctly.
In the documentation for the GoodBarber Plugin API, you will find the definitions of the callbacks that can be
implemented, as well as an example of implementation.

Callbacks can be called by the application for two main reasons:

- A method call requiring a response
- During the life cycle of your plugin (methods documented in the Events Callbacks section)

4. Data accessible by default

In all of the pages of your plugin, you will have access to two JavaScript dictionaries.
gbUserInfo
Contains information on the terminal, the OS, etc.
{
"platform" : "ios" | "android",
"binaryVersion" : version of the application's binary,
"gbVersion" : version of the GoodBarer foundation,
"osVersion" : version of the OS terminal,
"deviceCode" : code name of the terminal (for example : "iPhone5,2"),
"language" : user language
}

gbPostData
Contains a dictionary of the parameters in POST following the call of the preceding method, in the case of navigation
methods.
{
...
}

2. 2. 2. Basic methods
In your GoodBarber HTML5 plugin, you can use "basic" methods, allowing interactions with the user's device.
These methods are also available in the Basic Custom sections.
Most of the basic methods can be called by launching a navigation to a standard URL scheme. They're also available, in
an easier way, in the GoodBarber JavaScript ToolKit.

1. Web Browser Navigation (http://)

If you want to start a navigation to an external URL - typically a web link- you can just call the link.
The http:// prefix will be interpreted by the app to be opened in the internal browser.
Example of a link to Google within a plugin:
<a href="http://www.google.com">Go on Google</a>

2. Mail Composer (mailto:)

Il you want to open the phone's Mail app composer, to allow your users to send an e-mail from your plugin, you just have
to launch a navigation towards a mailto: scheme.
According to the standard, a mailto: link can handle several parameters (to address, subject, body, etc.).
Example of mailto: link within a plugin:
<a href="mailto:contact@goodbarber.com?subject=Hello&body=GoodBarber">Send an e-mail</a>

3. Call (tel:)
If you want to start a phone call within your plugin, you can use the URL prefix tel:.

Warning: There are no alert before the phone call starts using the tel: method. If you want to ask your user for a
confirmation, you'll need to implement a confirmation alert.
Example of phone call within a plugin:
<a href="tel:+1(555)555-5555">Call +1 (555) 555-5555</a>

4. SMS Composer (sms:)

If you want to open the phone's SMS composer within your plugin, you can use the URL prefix sms:.
It is unfornately impossible to set the SMS body, but you can set a default recipient.
Example of SMS within a plugin:
<a href="sms:+1(555)555-5555">Text +1 (555) 555-5555</a>

5. Maps Link
The maps method allows to open directly the Maps native app on the user's device, with one or several parameters.
The parameters to include into the URL are the one which usually follow URLs like "http://maps.google.com" and
"http://maps.apple.com". You can find more information about these parameters in the Apple reference documentation.
The maps method allows you to send seamlessly the user to the dedicated native app of his device (Maps on iOS,
Google Maps on Android). If you want to send your users to a specific app (without the automatic choice), you can
directly make a link to the destination URL that will be opened into the in-app browser.
Example of the maps method usage:
<a href="goodbarber://maps?q=cupertino">Locate "Cupertino"</a>

6. Method : openapp (Open an app, or a link)

The openapp method allows you to open a custom URL scheme, if an app able to open it is installed on the user's
device, and to open a web URL if not.
URL parameters:
- scheme : the custom URL scheme of the app to be opened (has to be url encoded)
- url : the URL to open if the device can't handle the URL scheme
Example of the openapp method usage:
<a
href="goodbarber://openapp?scheme=twitter%3A%2F%2F&url=http%3A%2F%2Fwww.twitter.com">Open
Twitter app if it's installed, or go to the website otherwise</a>

the

7. Method : openExternal (Open an URL in the external browser)

The openExternal method allows you to open the phone's browser (and leave the app).
URL parameters:
- url : the URL to open
Example of the openexternal method usage:
<a href="goodbarber://openExternal?url=http%3A%2F%2Fwww.twitter.com">Open this link in the external browser</a>

8. Method : gotosection (Go to a section)

The gotosection method allows you to make a link to another section of your app.
URL parameters:
- id : the section identifier
NB : To find your sections ids, go to the Developer section of your GoodBarber backend.
Example of the gotosection method usage:

<a href="goodbarber://#!section=123456789">Open the news section of the app</a>

2. 2. 3. Navigation methods
Your plugin has to delegate its navigation to the app.
To do it, it will send messages to the app, using pre-defined methods, which will allow to pass arguments between its
pages.

1. Method : navigate.push
The push navigation is the basic transition (left to right) between two pages of your app. It is typically used to navigate
from a list of content to the detail view of an item.
Parameters to be passed in the URL :
- page : the .html file to link to, has to be in your plugin's bundle
It is also possible to intergrate POST parameters in your request, that will be accessible in the destination page as
JavaScript variables.
To pass POST arguments with a JavaScript navigation, use the GBJSToolKit.
Example of navigation without POST parameters:
<a href="goodbarber://navigate.push?page=detail">Go to the detail page</a>
Exemple of navigation with POST parameters, using the GB JS ToolKit:
<a href="javascript:gbPost('goodbarber://navigate.push?page=detail',{'mydata':'Example data'});">Go to the detail
page</a>

2. Method : navigate.modal
The modal navigation is a vertical transition mode between two pages of your app. It is typically used to enter a settings
screen.
Parameters to be passed in the URL :
- page : the .html file to link to, has to be in your plugin's bundle
It is also possible to intergrate POST parameters in your request, that will be accessible in the destination page as
JavaScript variables.
To pass POST arguments with a JavaScript navigation, use the GBJSToolKit.
Example of navigation without POST parameters:

<a href="goodbarber://navigate.modal?page=helloworld">Go to a modal page</a>

Exemple of navigation with POST parameters, using the GB JS ToolKit:
<a href="javascript:gbPost('goodbarber://navigate.modal?page=helloworld',{'mydata':'Example data'});">Go to a modal
page</a>

3. Method : navigate.back
When your plugin has made a navigation to another page, it is possible to go back manually.
To do it, you have to call the navigate.back method, without arguments or parameters.
Exemple of back navigation:
<a href="goodbarber://navigate.back">Go to the previous page</a>

2. 2. 4. HTTP Request method and callbacks

It is recommended that your plugin delegate the management of it's downloads to the application; and it is in fact
necessary to do so to benefit from the authentication mechanism of the GoodBarber API calls.
By using the download method, you can benefit from the application's automatic cache system.
When you request access to a remote resource you may specify if you wish to receive a version of the resource that
was previoulsy cached.
Following a download method call, your plugin may receive one of the following callbacks:

- gbRequestDidFail ( tag, errorCode, errorMessage )

- gbRequestDidSuccessWithCache ( tag, data, src )
- gbRequestDidSuccess ( tag, data, src )

1. Method : request
The request method simply allows you to request access to a remote resource.
You must specify the following parameters:
- url: The URL of the resource you wish to access (must be URL encoded)
- tag: a tag (integer) to identify your request
YES
if
you
wish
to
receive
a
cached
version
if
cache:
callback gbRequestDidSuccessWithCache, otherwise NO
- method: (optional) the HTTP method will be used in the request (default value: GET)

there

is

one,

via

the

You may call this method with POST parameters, that will also be passed on to the body of the request.
Example of the download of a JSON stream in GET with a request for a cached version, if there is one:
<a
href="goodbarber://request
?url=http%3A%2F%2Fwww.monsite.com%2F/monjson.com&tag=1&cache=YES">Tlcharger le JSON</a>
Example of the download of an image in GET without callback for a cached version:
<a
href="goodbarber://request
?url=http%3A%2F%2Fwww.monsite.com%2F/monimage.jpg&tag=2&cache=NO">Tlcharger l'image</a>

2. Request pathway

3. Callback : gbRequestDidFail
The callback gbRequestDidFail is called if the request fails. It is strongly recommended to implement this callback
method to correctly handle request fails.
The method must include three parameters:
- tag : the tag (integer) defined at the call of the request
- errorCode : 0 if there is a network problem, the HTTP error code otherwise
- errorMessage : a description of the problem leading to the request failure

4. Callback : gbRequestDidSuccessWithCache
The callback gbRequestDidSuccessWithCache is called immediately before the beginning of the HTTP request if the
called resource is present in the application's cache (and the request was called with the cache parameter set to YES).
The method to be implemented must contain three parameters:
- tag: the tag (integer) defined at the request call
- data: the raw data of the resource
- src: the pathway to the resource in the file system

5. Callback : gbRequestDidSuccess
The callback gbRequestDidSuccess is called in case of a success of the HTTP request.
The method to be implemented must contain three paramters:
- tag: the tag (integer) defined at the request call
- data: the raw data of the resource
- src: the pathway to the resource in the file system

2. 2. 5. Other methods
In your HTML5 plugin for GoodBarber, you can use methods that allow you to access a certain number of "advanced"
features of the application or terminal.
The majority of these methods send a JavaScript callback indicating the success or failure of the method.

1. Method : authenticate
You may request that users identify themselves to access a feature, through an "authenticate" method call. In this
instance, you may specify which services (Facebook or Twitter) you wish to use for authentication.
Arguments in the URL:

|facebook|twitter
- skip: possible values:: YES (by default, allows the user to abandon the
login process) | NO (force the user to log in)
- services: possible values: all (by default)

If the value "all" is given for the services parameter, a transparent design is added to plugin view to ask the user through
which service they wish to authenticate. If the parameter skip is not given (or set to YES), a button will allow the user to
abandon the login. If the value is NO, the user will be forced to choose a service to log in.
If the user is already logged in to the app through at least one of the services in the application, the login action will be
transparent.
When the authentication process is finished, two callbacks can be called:
- gbDidSuccessAuthentication ( socialUser )
- gbDidFailAuthentication ( errorMessage )
Example of an authentication request through one of the services (without distinction)
<a href="goodbarber://authenticate?services=all">S'authentifier</a>
Example of an authentication request through Facebook only:
<a href="goodbarber://authenticate?services=facebook">S'authentifier via Facebook</a>
Example of an authentication request via one of the services (without distinction, authentication mandatory):
<a href="goodbarber://authenticate?services=all&skip=NO">S'authentifier</a>

2. Callback : gbDidSuccessAuthentication
The callback gbDidSuccessAuthentication is called if the authentication succeeded. The parameters regarding the user
are stored as a callback parameter, via a dictionary.

The method to be implemented must contain a parameter:

- socialUser: a dictionary containing the information pertaining to the authenticated user (the format is described in the
following)
Format of the dictionary in the parameter socialUser:
{
"serviceType" : "facebook" | "twitter",
"id" : identifiant de l'utilisateur sur le service,
"profileUrl" : url de profil de l'utilisateur,
"username" : nom d'utilisateur (username),
"name" : nom (real name) de l'utilisateur,
"profilePictureUrl" : url de la photo de profil,
"gender" : genre ("male" | "female"),
"birthdate" : date de naissance,
"language" : langue parle par l'utilisateur,
"location" : localisation de l'utilisateur renseigne sur le service,
"nbConnections" : nombre de connexions de l'utilisateur (amis ou followers),
}

3. Callback : gbDidFailAuthentication
The callback gbDidFailAuthentication is called if the authentication fails (typically if the user has not consented to the
authentication).
The method to be implemented must contain a parameter:
- errorMessage: a message describing the cause of the authentication failure

4. Method : share
You may use the share method to make sharing content in the social networks easy for your users, directly from the
sharing module integrated into your GoodBarber app.
Arguments passs dans l'URL :
- text : le texte partager (doit tre URL encod)
- link : (optionnel) le lien partager (doit tre URL encod)
Arguments in the URL:
- text: the text to be shared (must be URL encoded)
- link (optional): the link to be shared (must be URL encodedExample of a share module with text:
<a href="goodbarber://share?text=Hello%20from%20my%20plugin%20!">Partager un texte</a>
Example of a share module with text and a link :
<a href="goodbarber://share?text=Hello%20from%20my%20plugin%20!&link=http%3A%2F%2Fwww.goodbarber.com">
Partager un texte et un lien</a>

5. Method : getmedia
The getmedia method allows you to call a terminal to obtain a photo or a video. You may restrict the type of content that
you wish to obtain via this method, as well as the source (direct capture or choice in the albums).
Arguments in the URL :
- type : possible values : photo (by default) | video
- source : possible values : all (by default) | camera | library
If the value of the parameter source is left empty or set to "all" (default value), a menu will ask the user to choose if they
wish to take a photo (or video) directly, or if they wish to choose one from an album. The value of the parameter type is
transparent to the user: the user can only choose the corresponding media in the selection menu.

When the authentication process is finishes, two callbacks can be called:

- gbDidSuccessGetMedia ( data, src )

- gbDidFailGetMedia ( errorMessage )
Example of a method call getmedia: (asks the user for a photo, distinct from the camera)
<a href="goodbarber://getmedia">Capturer ou choisir une photo</a>
Example of a method call getmedia (opens the camera)
<a href="goodbarber://getmedia?type=photo&source=camera">Prendre une photo</a>
Example of a method call getmedia (request to choose a video from an album):
<a href="goodbarber://getmedia?type=video&source=library">Choisir une vido</a>

6. Callback : gbDidSuccessGetMedia
The callback gbDidSuccessGetMedia is called if the media retrieval was successful.
The method to implement must comprise two parameters:
- data: the raw image or video data
- src: the pathway to the resource on the drive

7. Callback : gbDidFailGetMedia
Le callback gbDidFailGetMedia est appel si la capture du media a chou.
La mthode implmenter doit comporter un paramtre :
- errorMessage : un message dcrivant la cause de l'chec
The callback gbDidFailGetMedia is called if the media retrieval failed.
The method to be implemented must contain a parameter:
- errorMessage: a message describing the reasons for failure.

8. Method : getlocation
The method getlocation allows you to call the terminal to obtain the user's geolocation data. This method does not
require any arguments.
It may send one of two callbacks:
- gbDidSuccessGetLocation ( lat, long)
- gbDidFailGetLocation (errorMessage)

9. Callback : gbDidSuccessGetLocation
The callback gbDidSuccessGetLocation is called if the geolocation of the user succeeded.
The method to be implemented must contain two parameters:
- lat: latitude of the user
- long: longitude of the user

10. Callback : gbDidFailGetLocation

The callback gbDidFailGetLocation is called if the geolocation of the user failed.
The method to be implemented must contain a parameter:
- errorMessage: a message describing the reason of the failure

11. Method : gettimezoneoffset

The method gettimezoneoffset allows you to call the terminal to get the time difference between UTC time and local
time, in minutes.

It will send one callback :

- gbDidSuccessGetTimezoneOffset ( offset )

12. Callback : gbDidSuccessGetTimezoneOffset

The callback gbDidSuccessGetLocation is called when the difference is got.

The method to be implemented must contain this parameter:

- offset: time difference between UTC time and local time, in minutes

2. 2. 6. Events callbacks
Events callbacks are called by your plugin as a function of the App Lifecycle and the user's actions (when content is
shown, when the app goes into background mode or is retrieved from background mode, etc.)
They are designed to help you manage the display of your content at the right time. Even if they are not useful all the
time, it is nevertheless recommended to implement them to optimize the user experience.

1. Callback : gbAppWillEnterBackground
The callback gbAppWillEnterBackground is called when app goes into background mode.
Example of implementation:
function gbAppWillEnterBackground()
{
// Do something
}

2. Callback : gbAppDidBecomeActive
The callback gbAppDidBecomeActive is called when the app comes back from background mode.
Example of implementation:
function gbAppDidBecomeActive()
{
// Do something
}

3. Callback : gbPluginDidLoad
The callback gbPluginDidLoad is called when the plugin finishes loading.
Example of implementation :
function gbPluginDidLoad()
{
// Do something
}

4. Callback : gbViewDidLoad
The callback gbViewDidLoad is called when the current view finishes downloading.
Implementation example:
function gbViewDidLoad()
{
// Do something
}

5. Callback : gbViewWillAppear
The callback gbViewWillAppear is called just before the current view is displayed on the screen.
Implementation example:
function gbViewWillAppear()
{
// Do something
}

6. Callback : gbViewDidAppear
The callback gbViewDidAppear is called just after the current view is displayed on the screen.
Implementation example:
function gbViewDidAppear()
{
// Do something
}

7. Callback : gbViewWillDisappear
The callback gbViewWillDisapper is called just before the current view disappears from the screen.
Implementation example:
function gbViewWillDisappear()
{
// Do something
}

8. Callback : gbViewDidDisappear
The callback gbViewDidDisappear is called just after the current view disappears from the screen.

Implementation example :
function gbViewDidDisappear()
{
// Do something
}

2. 3. GoodBarber JavaScript ToolKit

2. 3. 1. GBJS ToolKit Overview
To use the GoodBarber plugin API, you may use the GoodBarber JavaScript ToolKit. This is a collection of utility
functions in JavaScript that can be used to facilitate the use of certain methods of the plugin API.
You will find three main types of tools:
- Debugging parameters (activating alerts, deactivation of requests, etc.)
- Various utility functions (contruction of URLs, sending of GET and POST requests, etc.)
- Encapsulation functions of the GoodBarber Plugin API
The GoodBarber plugin API is updated regularly, you can download the latest version from GoodBarber's GitHub profile
(where you will also find examples of plugins).

1. How to use the GB JS ToolKit in your plugin

Pour utiliser le GoodBarber JavaScript ToolKit dans votre plugin, tlchargez-en la dernire version en date sur le
profil GitHub de GoodBarber.
To use the GoodBarber JavaScript ToolKit in your plugin, download the latest version from GoodBarber's GitHub profile.
Add the JavaScript file

"GBJSTK.js" to the file bundle of your plugin.

In the HTML code of the of the pages of the plugin that require it, add this line to the HEAD tag.
<script language="JavaScript" src="./GBJSTK.js"></script>

2. 3. 2. GBJS ToolKit Documentation

This is a list of the parameters and methods available in the GoodBarber JavaScript ToolKit.

1. Var : int gbDebuggingMode

Sets the debugging mode using a system of code values.

Values :
- 0 : Production mode
- 1 : Alerts before any request
- 2 : Alerts before any request + stop requests

2. Function : gbIsEmpty
This function tests if an object is empty.

Arguments :
- obj : The action of the form

Return :
- true : if the object is empty
- false : otherwise

3. Function : gbConstructQueryString
This function constructs a query string using the "params" dictionary.

Arguments :
- params : The params to construct the query string

Return :
The constructed query string

4. Function : gbPostRequest
This function creates a form in document.body and sends a POST request to "path" using "getParams" and
"postParams".

Arguments :
- path : The action of the form
- params : The parameters to send in the request body

5. Function : gbGetRequest
This function launches a navigation to "path" setting "params" as GET arguments.

Arguments :
- path : The destination path
- params : (optional) The params to send in the request body

6. Function : gbMailto
Launches the mail composer.
Arguments :
- to : The destination address
- subject : (optional) The mail subject
- body : The (optional) mail content

7. Function : gbTel
Launches a call.
Arguments :
- phoneNumber : The number to call

8. Function : gbSms
Launches the SMS composer.
Arguments :
- phoneNumber : The number to send a text to

9. Function : gbMaps
Launches the Maps native application.

Arguments :
- params : The parameters to pass in the query string

10. Function : gbOpenApp

Tests if the current device can handle the URL scheme ("scheme" param), if so opens it, or opens the url ("url" param)
otherwise.

Arguments :
- scheme : The URL scheme to test
- url : The URL to launch otherwise

11. Function : gbGoToSection

Goes to the section identified by its "id".
Arguments :
- id : The id of the destination section

12. Function : gbNavigatePush

Launch a push navigation between two pages of the plugin.

Arguments :
- page : The destination page
- postParams : The postParams to give to the destination page

13. Function : gbNavigateModal

Launch a modal navigation between two pages of the plugin.
Arguments :
- page : The destination page
- postParams : The postParams to give to the destination page

14. Function : gbNavigateBack

Launch a back navigation between two pages of the plugin.

15. Function : gbRequest

Starts a request to the url resource, using the "method" method, and passing the "postParams" params if
method==POST.

Arguments :
- resourceUrl : The url of the resource to load
- tag : A tag to identify the request
- cache : YES if you want to use the app's cache mechanism, NO otherwise
- requestMethod : The HTTP method you want to use for the request

- postParams : If method==POST, you can pass HTTP Post Params in your request
Callbacks :
- gbRequestDidFail ( tag, errorCode, errorMessage )
- gbRequestDidSuccessWithCache ( tag, data, src )
- gbRequestDidSuccess ( tag, data, src )

16. Function : gbAuthenticate

Ask the user to authenticate on a social network.

Arguments :
- services : The services to use for the authentication | values : [all(default)|facebook|twitter]
- skip : Give the user the possibility to skip the authentication process | values : [YES(default)|NO]
Callbacks :
- gbDidSuccessAuthentication ( socialUser )
- gbDidFailAuthentication ( errorMessage )

17. Function : gbShare

Ask the user to share a content on a social network.
Arguments :
- shareText : The text to share
- shareLink : The link to share

18. Function : gbGetMedia

Asks the user to take or choose a picture/movie.
Arguments :
- mediaType : The type of media that you want the user to take or choose | values : [photo(default)|video]
- mediaSource : The source (camera or library) | values : [all(default)|camera|library]
Callbacks :
- gbDidSuccessGetMedia ( data, src )
- gbDidFailGetMedia ( errorMessage )

19. Function : gbGetLocation

Asks for the users geolocation.
Callbacks :
- gbDidSuccessGetLocation ( lat, long )
- gbDidFailGetLocation ( errorMessage )

20. Function : gbGetTimezoneOffset

Asks for the time difference between UTC time and local time, in minutes.

Callbacks :
- gbDidSuccessGetTimezoneOffset( offset )

2. 4. Examples & Tutorials

2. 4. 1. Tutorial : How to implement a basic Navigation
If your plugin must display it's content over several pages (typically for a list of a content and a page from that list), you
must delegate the navigation between these pages to the plugin in order to be able to benefit from native transitions.
To do so, the Plugin API and the GoodBarber JavaScript ToolKit offer two different methods:
- Push navigation (in depth)
- Modal navigation (transversal)
In this example, we're going to use the GoodBarber JavaScript ToolKit.

1. Objective
In this example, we want to create a plugin with three pages:
- The main page (index.html)
- A detail page (detail.html)
- A modal page (modal.html)
The main page (index.html) will comprise two clickable zones triggering a navigation: one towards the detail page (in
push navigation) and one to the modal page (in modal navigation).
Each of the two targeted pages (detail.html and modal.html) will contain a zone that will trigger a return within the
navigation hierarchy (back navigation).

2. 1. Creating the index.html page

Nous allons commencer par crer la page index.html.
Nous allons y crer les deux <div> correspondant aux zones cliquables, et y associer des actions (via l'attribut onClick)
dclenchant respectivement les mthodes gbNavigatePush et gbNavigateModal.
We will create the two <div> corresponding to the two clickable zones, and associate further actions (via the
attribute onClick) triggering the methods gbNavigatePush and gbNavigateModal, respectively.
This is the content of the <body> tag in the index.html file:
<h1>Home</h1>
<div class="zone" onClick="javascript:gbNavigatePush('detail', {});">Push Navigation</div>
<br />
<div class="zone" onClick="javascript:gbNavigateModal('modal', {});">Modal Navigation</div>
In both instances, the first argument of the method corresponds to the targeted page (without the extension), and the
second to the data that may need to be transmitted to the destination page.

3. 2. Creating the detail.html and modal.html pages

In these two pages, we will create a <div> that will correspond to a clickable zone allowing a return back within the
navigation. This will done through a call to the method gbNavigateBack.
This is the content of the <body> tag in the detail.html file:
<h1>Detail</h1>
<div class="zone" onClick="javascript:gbNavigateBack();">Back Navigation</div>

This is the content of the <body> tag in the modal.html file:

<h1>Modal</h1>
<div class="zone" onClick="javascript:gbNavigateBack();">Back Navigation</div>

4. 3. Result
You can now easily test the navigation by downloading this sample plugin from GoodBarber's GitHub page, or by
following the steps outlined in paragraphs 1 and 2.

2. 4. 2. Plugin Example : Weather by Geolocation

In this example of a plugin, we will make a request to the API REST of the site Weather Underground to display the
current weather conditions as a function of the user's geographic location.
We will therefore attempt to search for the current location of the terminal (gbGetLocation method) and send the
requests to the network (gbRequest method).
This plugin is rather simple, it's purpose is to illustrate how to use the methods of the GoodBarber Plugin API.
Please note: This plugin uses the GoodBarber JavaScript ToolKit.

1. Architecture of the plugin

Le plugin n'a pas vocation implmenter une navigation car il se contente d'afficher 3 informations sur une seule page,
on ne retrouve donc que la page index.html.
This plugin won't implement a navigation as it is only intended to display three different types of information on one
page, therefore, one will not find the page index.html.
We have a CSS sheet (style.css), as well as several images for the plugin (in the following formats: .gif, .png, and .jpg).
Finally, there are two JavaScript files: The GoodBarber JavaScript ToolKit (GBJSTK.js) and the file of functions specific
to the plugin (plugin.js).

Please note: In order to ensure the optimal showing regardless of different screen types (particularly Retina and nonRetina screens) we have used media queries in the CSS sheet. By convention, the images in double size (for Retina
screens) carry the suffix "@2x", just like with native developments.

2. How the plugin works

The operation of this plugin is relatively simple: Once it's instantiated, it will trigger it's refresh method, which will send a
cascade request to obtain the geolocation of the user.
If this request is successful, a request will be sent to the Weather Underground API.
If the API works correctly, the page will be refreshed with the current information. Otherwise, the user will be informed
that an error has occurred during the update process.
A click on the refresh button will re-start the refresh process.

3. How can I test this plugin?

In order to test this plugin in your GoodBarber app, download it from GoodBarber's GitHub profile, and then import it to a
plugin section in your GoodBarber backend.
You can then modify it in order to discover the possibilities provided by the GoodBarber Plugin API and the GoodBarber
JavaScript ToolKit.
You simply need to sign up (for free) on Weather Underground (http://www.wunderground.com/weather/api/) to get an
API key, which you will then need to insert at the top of the file plugin.js.

3. Content API
3. 1. Content API Overview
3. 1. 1. Content API Overview
The GoodBarber Content API allows you to access the content synchronized form the different sources that you have
plugged in your sections.
The Content API is built on a REST architecture. On each source, it's possible to call different methods, each meeting a
specific need.
The Content API requests are secured and can be called only from the app itself (or by a plugin in the app). To
facilitate your tests, you can use an API Console in your backend.
The auth management in the Content API is handled automatically by the request method of the GoodBarber Plugin
API.

1. General structure of Content API requests

The Content API calls URLs always follow this structure:

http://[myapp].goodbarber.com/apps/[endpoint]/[section_id]/[arguments...]
You can find the list of available sources for your app in your GoodBarber backend.
The detailed list of endpoints is described in this article : Endpoints List.

2. General structure of Content API responses

The responses of the Content API are always formatted as a JSON dictionary, and follow a general structure.
The responses contain an array of items resulting of the request, and several other informations.
The structure of the Content API responses is detailed in this article : Return structures & values.

3. Item type and inherited types

The data returned by the Content API is always formatted as JSON dictionaries respecting the Item format.
Each entry (article, video, tweet, photo, event, etc.) is an Item, having several additional keys specific to its type.
The Item format specifications and the additional keys for each type are described in this article : Items types
documentation.

3. 1. 2. Content API Use Policy

1. Authentication and use of the Content API
The GoodBarber Content API calls are secure through a auth system, not documented.
The GoodBarber Plugin API gives access to methods that encapsulate the authentication and make it transparent in
calls. Only requests to a section belonging to the app itself can be authenticated.
The GoodBarber Content API should be used only in Plugins developed for GoodBarber apps.

2. Content API modifications

The requests and responses of the Content API can change anytime. It's important to follow the GoodBarber blog and
this documentation.

3. 2. Content API Documentation

3. 2. 1. Endpoints List

The Content API endpoints allow you to access the content synced in your GoodBarber backend.
Some sources allow only basic endpoints. To get the precise list of available endpoints for each source, have a look to
the list of sources of your app.

1. /getLastItems
The /getLastItems endpoint returns a list of items from the source plugged in the section "section_id", in a reverse
chronological order, and using the page and per_page parameters.
Args :
- section_id : the section id of the section connected to the source
- page : page to call, calculated using per_page
- per_page : number of items to return for this page
Call structure :
/getLastItems/[section_id]/[page]/[per_page]/

2. /getPopularItems
The /getPopularItems endpoint returns a list of items from the source plugged in the section "section_id", in a popularity
order, and using the page and per_page parameters.
Args :
- section_id : the section id of the section connected to the source
- page : page to call, calculated using per_page
- per_page : number of items to return for this page
Call structure :
/getPopularItems/[section_id]/[page]/[per_page]/

3. /search
The /search endpoint returns a list of items from the source plugged in the section "section_id", filtered using the
keyword arg, and using the page and per_page parameters.
Args :
- section_id : the section id of the section connected to the source
- keyword : keyword to search (has to be url encoded)
- page : page to call, calculated using per_page
- per_page : number of items to return for this page
Call structure :
/search/[section_id]/[keyword]/[page]/[per_page]/

4. /getItem
The /getItem endpoint returns the item having the id item_id on the connected source of the section section_id.
Args :
- section_id : the section id of the section connected to the source
- item_id : id of the item to return
Call structure :
/getItem/[section_id]/[item_id]/

5. /getItemByUrl
The /getItemByUrl endpoint returns the item having the url item_url on the connected source of the section section_id.
Args :
- section_id : the section id of the section connected to the source
- item_url : URL of the item to return

Call structure :
/getItemByUrl/[section_id]/[item_url]/

6. /getCategories
The /getCategories endpoint returns the list of categories of the connected source of the section section_id, using the
page and per_page parameters.
Args :
- section_id : the section id of the section connected to the source
- page : page to call, calculated using per_page
- per_page : number of items to return for this page
Call structure :
/getCategories/[section_id]/[page]/[per_page]/

7. /getItemsByCategorie
The /getItemsByCategorie endpoint returns a list of items from the source plugged in the section "section_id", filtered
using the category_id arg, and using the page and per_page parameters.
Arguments :
- section_id : the section id of the section connected to the source
- category_id : id of the category
- page : page to call, calculated using per_page
- per_page : number of items to return for this page
Call structure :
/getItemsByCategorie/[section_id]/[category_id]/[page]/[per_page]/

3. 2. 2. Return structure &amp; values

1. Response of the Content API
Each response of the Content API is designed to not generate more calls. The returned items are always full.
Except for the Facebook and Soundcloud sources, which are very specific cases, the items returned for a call will
always have the same type.
The responses of the GoodBarber Content API are always done in JSON, and have always the same structure :
{
"generated_in" : "...",
"items" : [...],
"next_page" : "...",
"stat" : "...",
"title" : "...",
"url" : "..."
}

2. Keys
Name
generated_in
items
next_page

Type
String
Array of Items
String

stat

String

title

String

Description
Generation time of the response
Array of items to be returned
URL of the next_page to call
(calculated with the page and per_page
args)
Status of the response ("ok" is
everything is fine, "error" otherwise)
Title of the source

url

String

URL of the source

3. 2. 3. Item types documentation

Each entry returned by the GoodBarber Content API is formatted on a generic Item dictionary type.
The Item entries have common keys, and specific additional keys according to their type and subtype.
In the list below, for the specific types (articles, videos, etc.) inherited from Item, only the additional keys described.

1. Item (common)
Generic Item type, every other type inherits from Item.
Name
id
type
title
url
categories

Type
String
String
String
String
Array of Strings

date
author
subtype

String (date)
String
String

Description
Item unique identifier on its source
Item type
Item title
Item URL on its source
Categories associated with the item on
the source
Item publication date
Item author
Item subtype (generally describes the
service type of the source)

2. Article
Inherited from Item, can be displayed in Article sections.
type = article
subtype = wordpress, typepad, wmaker, rss, etc.
Name
nbComments

Type
Integer

commentsEnabled

Bool

commentsUrl

String

commentsPostUrl

String

summary

String

content
smallThumbnail
thumbnail
largeThumbnail
images
images/[]/id

String
String
String
String
Array of Dict
String

images/[]/url
String
Specifications to follow are described here : Articles sources.

Description
Number of comments associated with
the item on its source
Describes if the comments have to be
enabled or not for this item
URL to access the JSON feed of
comments for this item
URL that allows to post comments on
this item
Summary of the article (no HTML, text
only)
Article content
Article thumbnail (small format)
Article thumbnail (medium format)
Article thumbnail (big format)
List of images contained in the article
Value of the id attribute of the <img>
tags in article content
Image URL

3. Photo
Inherited from Item, can be displayed in Photo sections.
type = photo
subtype = flickr, facebook, wmaker, picasa, etc.
Name
content
nbLikes

Type
String
Integer

Description
Photo description (text only, no HTML)
Number of likes of the photo (only if

nbComments
commentsEnabled

Integer
Bool

commentsUrl

String

commentsPostUrl

String

images

Dict

images/{SIZE}/height
images/{SIZE}/width
images/{SIZE}/url
Indicative values of {SIZE}
Value
square
largesquare
small
medium
large

Integer
Integer
String

subtype = facebook)
Number of comments
Describes if the comments have to be
enabled or not for this item
URL to access the JSON feed of
comments for this item
URL that allows to post comments on
this item
Dictionary of the different sizes
available for the photo
Height of the photo
Width of the photo
URL of the photo

Description
Small format (square)
Medium format (square)
Small format (original proportions)
Medium format (original proportions)
Big format (original proportions)

Indicative values
75x75
150x150
240x180
320x240
640x480

4. Vido
Inherited from Item, can be displayed in Video sections.
type = video
subtype = youtube, dailymotion, vimeo, wmaker, facebook, etc.
Name
nbComments
commentsEnabled

Type
Integer
Bool

commentsUrl

String

commentsPostUrl

String

content
summary

String
String

smallThumbnail
thumbnail
largeThumbnail
nbViews
length
rating
nbRatings
videoUrls

String
String
String
Integer
Integer
Float
Integer
Dict

videoUrls/{VIDEO_TYPE}

String

videoUrl

String

nbLikes

Integer

image

String

Possible keys for {VIDEO_TYPE}

Value
m3u8
mp4
embed

Description
Number of comments
Describes if the comments have to be
enabled or not for this item
URL to access the JSON feed of
comments for this item
URL that allows to post comments on
this item
Video description
Summary of the video (no HTML, text
only)
Video thumbnail (Small format)
Video thumbnail (Medium format)
Video thumbnail (Big format)
Number of views of the video
Video duration (seconds)
Medium rating of the video
Number of ratings of the video
Dictionary containing the different
formats for the video source
URL of the video resource
corresponding to {VIDEO_TYPE}
URL to watch the video (only if
subtype = facebook)
Number of likes of the video (only if
subtype = facebook)
Video original thumbnail URL (only if
subtype = facebook)

Description
URL of the HTTP Streaming feed
URL of the MP4 file
URL that could be indicated as the
source of an HTML embed to watch the

Format
Apple HTTP Streaming
MP4
HTML embed

embedHTML

video
HTML full embed code of the video

HTML embed

5. Event
Inherited from Item, can be displayed in Event sections.
type = event
subtype = facebook, google, wmaker, etc.
Name
address
allDay

Type
String
Bool

content
endDate
latitude

String
String (date)
String

longitude

String

thumbnail

String

Description
Address of the event
Describes if the event is an "all day"
event
Event description
End date of the event
Latitude of the event (GPS
coordinates)
Longitude of the event (GPS
coordinates)
Thumbnail of the event

6. Sound
Inherited from Item, can be displayed in Sound sections.
type = sound
subtype = podcast, soundcloud, etc.
Name
nbComments
commentsEnabled

Type
Integer
Bool

commentsUrl

String

commentsPostUrl

String

length
nbFavorites

Integer
Integer

purchaseUrl
streamUrl
summary
thumbnail

String
String
String
String

Description
Number of comments
Describes if the comments have to be
enabled or not for this item
URL to access the JSON feed of
comments for this item
URL that allows to post comments on
this item
Duration of the podcast (seconds)
Number of "favorites" by user for this
song (only if subtype = soundcloud)
URL to buy the song
Stream URL for this podcast
Description of this podcast
Thumbnail URL

7. Twitter
Inherited from Item, can be displayed in Twitter sections.
type = twitter
subtype = twitter
Name
authorAccount
since

Type
String
Integer

content
thumbnail

String
String

8. Facebook - Page
Not-inherited type, used as header for Facebook sections.
type = facebook_page
subtype = facebook

Description
Author's twitter account for this tweet
Time spent since the publication of
this tweet (seconds)
Tweet content
Tweet thumbnail URL (generally,
author's profile picture)

Name
author
categories

Type
String
String

content
cover
founded

String
String
String

id
nbLikes
subtype
thumbnail
title
type
url
urlScheme

String
Integer
String
String
String
String
String
String

Description
Page username
Page category (has to be a Facebook
category)
Page description
Cover picture URL
Creation date as filled on the
Facebook page settings
Facebook profile identifier
Number of likes on the Page
In this case, always "facebook"
Profile picture URL
Name of the Facebook page
In this case, always "facebook_page"
Page URL
Deep URL to access the Facebook
page in the iOS Facebook app

9. Link
Inherited from Item, can be displayed in Facebook sections (link items).
type = link
subtype = facebook, etc.
Name
nbComments
nbLikes
thumbnail
caption
description
link

Type
Integer
Integer
String
String
String
String

Description
Number of comments
Number of likes
Thumbnail URL for this link
Link caption
Link description
Link target (URL)

10. Status
Inherited from Item, can be displayed in Facebook sections (status items).
type = status
subtype = facebook, etc.
Name
nbComments
nbLikes
content

Type
Integer
Integer
String

Description
Number of comments
Number of likes
Status content

11. Comment
Inherited from Item, can be displayed in comment pages.
type = comment
subtype = wordpress, wmaker, etc.
Name
content

Type
String

Description
Content of the comment

12. Live Plus

Inherited from Item, can be displayed in Live+ sections.
type = live
subtype = liveplus
Name
artist
title

Type
String
String

Description
Artist name
Song's title

cover
duration
albumTitle
year

String
Integer
String
Integer

URL of the song/album cover

Song duration (seconds)
Album title
Anne de parution de la chanson

3. 3. Items types specific rules

3. 3. 1. Article sources
The Article sources (WordPress, TypePad, WMaker, RSS, etc.), that can be displayed in Article sections have several
specificities in their Content API responses.
In each case, an Article source should return only items having an "article" type, and the subtype can vary (ex:
"wordpress", "typepad", "wmaker", etc.).

1. Specific management of images in article's content

To allow the app to cache the images of the article, the images URLs mentioned in the article content have to appear in
the array of dictionary images.
NB: The "id" attribute of the <img> tags contained in the article HTML code have to match the "id" key of a dictionary of
the "images" array of the item.

2. Summary
The summary attribute content will be displayed at the list level in the app.

3. Thumbnail management
The article items return 3 thumbnails formats, that will be chosen by the app according to the active list template. Here
are some indicative sizes:
- smallThumbnail : 158x82
- thumbnail : 314x164
- largeThumbnail : original size of the image

3. 3. 2. Video sources
The Video sources (YouTube, Dailymotion, Vimeo, WMaker, etc.), that can be displayed in Video sections have several
specificities in their Content API responses.
In each case, an Article source should return only items having an "video" type, and the subtype can vary (ex:
"youtube", "dailymotion", "wmaker", etc.).

1. Specific management of the different video formats / embed

The "content" key of the dictionary shouldn't contain the embed code of the video. Only its description (that can be
formatted in HTML) has to be returned.
The app inserts itself a button that allows the user to access the video in the detail page, using the values of the
videoUrls dictionary. Here is the priority order of the dictionary entries:
1. embedHTML => If there is an embedHTML key, it's used in priority. Its content will be displayed without any
modification
2. m3u8 / mp4 => If there isn't an embedHTML key, the app will show a button linking to the direct URL streams of the
video
3. embed => If there isn't any direct stream URL for the video, the app will show an <iframe> having this key as source

2. Thumbnails management
The video items return 3 thumbnails formats (in 16/9 ratio), that will be chosen by the app according to the active list
template. Here are some indicative sizes:
- smallThumbnail : 179x100

- thumbnail : 300x168
- largeThumbnail : original size of the image

3. 4. Build your own Custom Feeds

3. 4. 1. How to create your own Custom Feeds?
You can create your own custom feeds, respecting the specifications of the Content API. Once these JSON content
feeds created on your website, you'll be able to add them as sources of your sections, using the Custom connector.
The values handled by the app are simple. Each element inherits from the Item type, and has some type specific
attributes (like articles, videos, events, photos, ...).
The values are described here : Item Types Documentation

You can download some examples here: Custom feeds examples

For each source type, it's possible to define several types of actions:
- getLastItems => get the last items published, or items for a specific filter (like categories filters)
- search => takes a [KEYWORD] argument to make a search in the website's content
- getCommentsByItem => get the comments associated to an item

NB : The names getLastItems, search, getItemByCategorie, getCommentsByItem described in the documentation are
the conventions that we use.
When you add a custom source, you'll have to enter the whole URL to access your custom feeds, so it's not mandatory
to respect this naming convention.

How to add a custom source in your sections

Powered by TCPDF (www.tcpdf.org)