Embed Campaigns, Stream and Comments into your mobile app or other site. Want more customization? Build your own look.
Integrate social login or data from Stream with this Javascript API library. The required input is your account number and Stream key values.
Download: tbits-sdk.js
Or link via script tag:
<script type="text/javascript" src="https://tradablebits.com/tbits-sdk.js"></script>
Initialization
TBITS.init(apiKey)
Initialize the TBITS SDK. Required for most other TBITS methods.
Parameters
- apiKey
String
Streams
new TBITS.Stream(streamKey)
Stream object constructor. The stream object contains all the calls relevant to the stream key.
Parameters
- streamKey
String
Stream SDK example
Simple fetch for all records in the Stream "mystream"
<script type="text/javascript" src="https://code.jquery.com/jquery-1.11.0.min.js"></script>
<script type="text/javascript" src="https://static.tradablebits.com/static/js/libs/moment.min.js"></script>
<script type="text/javascript" src="https://static.tradablebits.com/static/js/libs/underscore.js"></script>
<script type="text/javascript" src="https://tradablebits.com/tbits-sdk.js"></script>
<script type="text/javascript">
// Example of TBITS.Stream usage.
// Note: jQuery, moment.js, and underscore.js are optional.
// Code below is provided for reference only.
let stream;
$(document).ready(function() {
// Create an instance of the Stream object, passing it a stream key.
stream = new TBITS.Stream('mystream');
// Pull the records. This returns a Promise (like all Stream methods), so use then() and catch() for processing.
// Check the reference for additional options.
stream.getRecords({ is_graphic: true })
.then(recordsCallback)
.catch(err => {
console.error(err);
});
});
function recordsCallback(res) {
console.log(res.meta);
let recTemplate = $("#record-template").html();
let $results = $("#results");
for (let record of res.data) {
// Render the results. Modify to match your site.
$results.append(_.template(recTemplate)(record));
}
}
// Click Handler to track caption link clicks
$('body').on('click', '.item-caption a', () => {
let feedRecordId = this.parentNode.dataset.feedRecordId;
stream.trackClick(feedRecordId);
});
</script>
<script type="text/template" id="record-template">
<div class="item-record">
<div style="width:24px;height:24px;color: #f5f5f5;background-color: #333;float: left;">
<svg viewBox="-15 -15 110 110">
<use xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://tradablebits.com/static/svg/sprites.svg#<%-network%>-path"></use>
</svg>
</div>
<% if (image_url){ %>
<div class="item-image">
<img src="<%-image_url%>" onerror="return stream.reportBrokenRecord(<%= feed_record_id %>);" />
</div>
<% } %>
<div class="item-profile">
<div class="profile-image">
<% if (author_image_url && profile_url){ %>
<a href="<%= profile_url %>" target="_blank" onclick="stream.trackClick(<%=feed_record_id %>)">
<img src="<%= author_image_url %>" alt="" onerror="$(this).hide();"/>
</a>
<% }else{ %>
<img src="https://tradablebits.com/icons/author-placeholder.png"/>
<% } %>
</div>
<div class="profile-name">
<%-author_name %><br/>
<% if(author_screen_name && network=="twitter"){ %>
@ <%-author_screen_name%>
<% } %>
</div>
<% if (network == 'twitter') { %>
<div style="text-align: right;width:100%;">
<div class="twitter-actions">
<a class="item-links" href="https://twitter.com/intent/tweet?in_reply_to=<%= record_key %>">
<span class="reply"></span></a>
<a class="item-links" href="https://twitter.com/intent/retweet?tweet_id=<%= record_key %>">
<span class="retweet"></span></a>
<a class="item-links" href="https://twitter.com/intent/favorite?tweet_id=<%= record_key %>">
<span class="star"></span></a>
</div>
</div>
<% } %>
</div>
<div class="item-caption" data-feed-record-id="<%=feed_record_id%>">
<%= TBITS.Stream.convertLinks(caption, network, props) %>
</div>
<hr/>
<% if (record_url){ %>
<a href="<%-record_url%>" target="_blank" class="blank-link">
<div class="network-icon">
<svg viewBox="-5 -10 110 110">
<use xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="/static/svg/sprites.svg#<%- network %>-path"></use>
</svg>
</div>
</a>
<% }else{ %>
<div class="network-icon">
<svg viewBox="-5 -10 110 110">
<use xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="/static/svg/sprites.svg#<%- network %>-path"></use>
</svg>
</div>
<% } %>
<br/>
<p class="small creation-timestamp"><%= moment.unix(creation_timestamp).fromNow() %></p>
</div>
</script>
<div id="results"></div>
stream.getRecords(options)
Fetch the records from the server according to the selected filter and
options
Parameters
optionsObject
- limit
Number
- max number of records - networks
String
- comma separated list of networks - label
String
- return records only labelled with given label - is_graphic
Boolean
- return only records with non-empty image - min_time_key
String
- return records with time_key greater than given value * - max_time_key
String
- return records with time_key less than given value - q
String
- text search for caption - start_latitude
Number
- GEO box for records with geo information - start_longitude
Number
- GEO box for records with geo information - end_latitude
Number
- GEO box for records with geo information - end_longitude
Number
- GEO box for records with geo information
Returns
Object
-
meta
Object
-
data
[Object]
- records that match the given options
stream.nextPage()
Given the conditions set previously with the
getRecords()
call, this function will return the following
records (i.e. with time_key greater than previous max time key).
Returns
Object
-
meta
Object
-
data
[Object]
- records that match the given options
stream.prevPage()
Given the conditions set previously with the
getRecords()
call, this function will return the previous
records (i.e. with time_key less than previous min time key).
Returns
Object
-
meta
Object
-
data
[Object]
- records that match the given options
stream.summary(options)
Return a summary view of the Stream.
Parameters
optionsObject
- data
String
- comma separated list of sections to include. Currently supports: words, labels, hashtags - label
String
- label name
Returns
Object
- approved_total
- stream_name
- stream_key
- total
- last_record_timestamp
Stream Summary Example
Generate a summary call with breakdown by label and include top keywords
<script type="text/javascript" src="https://tradablebits.com/tbits-sdk.js"></script>
<script type="text/javascript">
// Example of TBITS.Stream usage.
// Code below is provided for reference only.
let stream;
$(document).ready(function() {
stream = new TBITS.Stream('mystream');
stream.summary({data:"labels,words"}) // See reference for other available options.
.then(summaryCallback)
.catch(err => {
console.error(err);
});
});
function summaryCallback(res){
console.log('words', res.words);
console.log('labels', res.labels);
console.log(res.total + " total records");
}
</script>
stream.cube(options)
Return a breakdown by given dimensions for analytics purposes.
Parameters
optionsObject
- dimensions
String
- comma separated list of 'gender', 'author', 'label_key', 'network', 'country', 'province' - label_key
String
- Provides summary specific to the label
Returns
Object
- data
[Object]
- meta
Object
stream.getRecord(feedRecordId)
Return a single record given then ID
Parameters
- feedRecordId
Number
- ID of record to get.
Returns
Object
stream.authors(limit)
Get author records from the Stream. Display a Meta Facepile with this call.
Parameters
- limit
Number
- max number of authors (max 50)
Returns
[Object]
- author_id
Number
- network
String
- e.g. 'facebook' - user_key
String
- name
String
- image_url
String
stream.topAuthors(options)
Get Top Authors in the stream according to label
Parameters
- limit
Number
- sort_order
String
- 'reach' or 'vote_count' - label
String
Returns:
[Object]
- author_id
Number
- network
String
- user_key
String
- name
String
- image_url
String
- reach_count
Number
- posts
Number
stream.reportBrokenRecord(feedRecordId)
If a post is removed or made private on a social network, this post will be broken in the Stream and can be reported with this call. You can also use this call to report broken image URLs. The most common usage is to include a call to reportBrokenRecord() on an "onerror" event for the image.
Parameters
- feedRecordId
Number
- ID of record to report.
Returns
Boolean
stream.reportRecord(feedRecordId)
This call handles the "report" button for the public view of the Stream. Once reported, the post will be available in the moderation queue as reported by the user.
Parameters
- feedRecordId
Number
- ID of record to report.
Returns
Boolean
stream.createRecord(caption, recordMediaUid, options)
Use this call to create new record in the Stream. "caption" is the text associated with the record and recordMediaUid is a reference to the image uploaded with /upload_media call previously. See the examples below for more details.
Authenticated
When you callTBITS.getSession()
previously and initialize the profile,
createRecord()
will create a record tied to the profile
using the social network information.
Not-Authenticated
When createRecord is called directly you need to supply the options: name and email. They will be associated with the record instead of the profile.upload_image endpoint
upload_image endpoint is a HTTP url which can be used to upload binary images into the server for association with Stream records.Full url is "https://tradablebits.com/upload_media" and the only required parameter is form_uid which is client side generated unique identifier for the media. End point supports CONTENT_RANGE options and will return json data with media_uid which can be used for record creation upon success.
Parameters
- caption
String
- recordMediaUid
String
- uid of media uploaded to upload_image endpoint - options
Object
- include name, email, etc here.
Returns
Number
- the created record ID.
stream.trackClick(feedRecordId)
Use this call to track when a user clicks a link inside a record. This allows you to track which posts are trending in Stream Stats. The most common usage is to include a call to trackClick() on "onclick" events for a link.
Parameters
-
feedRecordId
Number
Returns
Boolean
TBITS.Stream.convertLinks(caption, network, props)
Utility function to identify and convert links in the caption
Campaigns (Apps)
Requires TBITS.init()
new TBITS.Campaign(apiKey, pageTabId)
Initialize the Campaign object using public API KEY and page tab id.
Note: You must also call init() to fetch the required details.
Parameters
- apiKey
String
- Public API Key - pageTabId
Number
- the id of the campaign to work with
campaign.init()
Additional step required to initialize the Campaign object. Sets the internal structure of the campaign object in order for other methods to work.
Returns
Object
- fields
[Object]
- a list of custom field objects - media
[Object]
- contains media_type objects that each contain a dictionary of media urls with the media_idx as the key - streamkey
String
- description
String
- rules
String
- label
String
- name_text
String
- quiz_questions
Object
- (for quiz like campaigns) - poll_options
object
- (for poll like campaigns) - tab_games
Object
- (for bracket, tug of war) - tab_deals
Object
- (for instantwin, coupons) - tab_items
Object
- (contains tab images)
campaign.getFanDetails()
Returns
Object
- fan_id
Number
- first_name
String
- last_name
String
- email
String
campaign.saveFanDetails(data)
Saves the fan data and adds the fan to the list of fans that participated in the campaign.
Parameters
- first_name
String
- last_name
String
- email
String
- is_subscribed
Boolean
- field_[crm_field_key]
String
- phone
String
- birthdate
String
(year-month-day)
data is a javascript object with the listed keys. name, email and is_subscribed are mandatory fields. For multiselect fields, use the same field_[crm_field_key] for each selected option
Returns
Object
- fan_id
Number
- first_name
String
- last_name
String
- email
String
campaign.fanLogout()
Deletes the fan's cookie to allow the next fan data to be saved. Should be used after saving a new fan and before saving another fan.
Returns
Boolean
campaign.trackShare(shareNetwork)
Call this each time the campaign is shared to track the shares to social
networks by fans. fan_network should be a string. The share will only be recorded if the fan has
authenticated using Facebook. See fanAuth()
Parameters
- shareNetwork
String
- e.g. 'facebook'
Returns
Boolean
<script async defer src="https://connect.facebook.net/en_US/sdk.js"></script>
<script type="text/javascript" src="https://code.jquery.com/jquery-3.3.0.min.js" ></script>
<script type="text/javascript" src="https://static.tradablebits.com/static/js/libs/underscore.js"></script>
<script type="text/javascript" src="https://tradablebits.com/tbits-sdk.js" ></script>
<script type="text/javascript" >
//An example usage of the APPS methods to collect and save fan input with and
//without Facebook authentication
let apiKey = "b9a18588-dfd3-4a20-94ef-16c70d571be4";
let pageTabId = 11;
let campaign;
$(document).ready(function () {
// Create the campaign object
campaign = new TBITS.Campaign(apiKey, pageTabId);
// Call init to finish setting up the campaign object. This returns a Promise.
campaign.init()
.then(initCallback)
.catch(err => console.error(err));
});
function initCallback(campaignData){
console.log(campaignData);
let templateData = { fields: campaignData.crm_fields };
let templateHtml = $("#fields_template").html();
$("#custom-fields").after(_.template(templateHtml)(templateData));
}
function getUserInput(){
let data = {}
$('.core').each(function() {
data[$(this).attr('name')] = $(this).val();
if($(this).attr('type') == 'checkbox') data[$(this).attr('name')] = this.checked;
});
$('.custom-field').each(function() {
data['field_'+$(this).attr('name')] = $(this).val();
});
return data
}
function noAuthSubmit(){
let data = getUserInput();
campaign.saveFanDetails(data).then(fanDetails => {
saveCallback(fanDetails);
campaign.fanLogout();
});
}
function saveCallback(fanDetails) {
console.log("Fan saved.", fanDetails);
}
</script>
<script type="text/template" id="fields_template">
<% for (let field of fields) { %>
<div class="form-group">
<label for="<%-field.crm_field_key%>"><%-field.title%></label>
<input type="text" name="<%-field.crm_field_key%>" class="form-control custom-field">
</div>
<% } %>
</script>
<div class='container'>
<div class='form'>
<h2> Core Fields </h2>
<div class="form-group">
<label for="first_name">First Name</label>
<input class="form-control core" type="text" name="first_name">
</div>
<div class="form-group">
<label for="last_name">Last Name</label>
<input class="form-control core" type="text" name="last_name">
</div>
<div class="form-group">
<label for="email">Email</label>
<input class="form-control core" type="text" name="email">
</div>
<div class="checkbox">
<label for='is_subscribed'>
<input class="core" type="checkbox" name="is_subscribed"> Subscribe
</label>
</div>
<h2 id='custom-fields'> Custom Fields </h2>
<button class='btn btn-default' onclick="noAuthSubmit();">No Auth Submit</button>
</div>
</div>
Counters
Requires TBITS.init()
TBITS.getCounter(counterName)
Obtain the value of the counter
Parameters
- counterName
String
Returns
Number
- The counter value
TBITS.updateCounter(counterName)
Increment the value of the counter by 1
Parameters
- counterName
String
Returns
Number
- The updated counter value
TBITS.checkCounter(counterName)
Check if user has voted previously and return counter together with status
Parameters
- counterName
String
Returns
Object
- voted
Boolean
- counter
Number
- The counter value
Counter Example
Simple fetch for all records in the Stream "mystream"
<script type="text/javascript" src="https://code.jquery.com/jquery-1.11.0.min.js" ></script>
<script type="text/javascript" src="https://tradablebits.com/tbits-sdk.js" ></script>
<script type="text/javascript" >
// Example of Counter usage.
// Note: jQuery is optional.
// Code below is provided for reference only
function callback(res){
var $counter = $("#counter");
$counter.html(res);
}
$(document).ready(function(){
TBITS.init('api key');
TBITS.getCounter('test_counter')
.then(callback)
.catch(err => {
// optionally handle errors
console.log(err);
});
});
function upVote(){
TBITS.updateCounter('testCounter')
.then(callback)
.catch(err => {
console.log(err);
});
}
</script>
<div id="counter"></div>
<a href="javascript:upVote()"> Vote </a>
Props
Requires TBITS.init()
TBITS.getProps(counterName)
Get custom meta data associated with specific property
TBITS.updateProps(counterName, props)
Update meta data associated with property
Idols
Requires a fan session fromTBITS.initSession()
and TBITS.getSession()
TBITS.getIdols()
Get the idols for the fan given the current session
Returns
[Object]
insertFanIdol(idolName)
Create idol-fan record for given idol name
Returns
[Object]
TBITS.removeFanIdol(idolName)
Remove idol-fan record for given idol name
Returns
[Object]
<script type="text/javascript" src="https://code.jquery.com/jquery-3.3.0.min.js" ></script>
<script type="text/javascript" src="https://tradablebits.com/tbits-sdk.js" ></script>
<script type="text/javascript" >
// Example of Idols usage.
// Note: jQuery is optional.
// Code below is provided for reference only
// Code implies previous use of TBITS.initSession(1) and this page is redirect back after authentication
$(document).ready(function() {
// Initialize TBITS with public API key.
TBITS.init('[apiKey]');
// Initialize session with Tradable Bits account id
let accountId = 1;
let code = location.hash.substr(1);
let callbackUrl = location.href;
TBITS.getSession(1,code,callbackUrl).then(res => {
console.log("Session Initialized, Session: ", res);
});
});
function getIdols() {
TBITS.getIdols()
.then(idolCallback)
.catch(err => console.error(err));
}
function insertJohnDoe() {
TBITS.insertFanIdol('John Doe')
.then(idolCallback)
.catch(err => console.error(err));
}
function removeJohnDoe() {
TBITS.removeFanIdol('John Doe')
.then(idolCallback)
.catch(err => console.error(err));
}
function idolCallback(idols) {
console.log(idols);
}
</script>
<a href="javascript:getIdols()"> Get Idols </a><br>
<a href="javascript:insertJohnDoe()"> Insert John Doe Idol </a><br>
<a href="javascript:removeJohnDoe()"> Remove John Doe Idol </a>
Authentication
TBITS.initSession(accountId, loginType)
This call will redirect the browser to authentication page. loginType can be left blank, at which point email authentication will be used. Upon successful authentication, we will redirect back to callback url as per CRM configuration. Resulting redirect will have a hashcode, which can be replaced for sessionUid via getSession call.
Arguments
- accountId - Tradable Bits Account ID. The account must have a valid subscription.
- loginType - Suggested login type: e.g. facebook, X, etc.
TBITS.closeSession()
Clears the session state locally on the browser side.
Returns
Boolean
TBITS.getSession(accountId, code, redirectUrl)
Upon successful authentication, we will redirect back to preconfigured redirect page. Hashcode will contain temporary code, which can be exchanged for session_uid via this call.
Returns
Object
- status - state of the session
- fan_id - identifier for the user record
- name - full name
- network - network of the source
- session_uid - Session Identifier
TBITS.optInFan(options)
Parameters
optionsObject
- first_name
String
- last_name
String
- email
String
- is_subscribed
Boolean
- phone
String
- display_name
String
- postal_code
String
- country_code
String
- city
String
- province
String
- field_*
String
- custom field values, e.g. field_favourite_colour - campaign_name
String
- tag_name
String
- device_id
String
- device_network
String
- is_unique_activity
Boolean
- ip_address
String
Returns
Object
- fan_id - identifier for the user record