About the Javascript SDK
Now that you've learned how to configure your Platform Account, you're ready to display your content. This document describes the TwineSocial Javascript SDK, which is a robust way to design engaging social applications for web applications.
Generally, the TwineSocial Javascript SDK works by providing a line of Javascript that you add to a brand website. The SDK retrieves and (optionally) renders contentItems
from your campaign into your HTML document. From here, you can apply your own CSS and Javascript to further manipulate your content, creating a seamless experience for the end user.
This document describes the configuration and display options available for retrieving, rendering, and reporting on engagements using the Javascript SDK.
Getting Started
To add the Javascript SDK to your website, first add the following script in your HTML document:
Next, add the following script into your HTML document to retrieve and render content:
This will retrieve 10 contentItems
from the "louboutin" campaign and append them to the #tiles
DIV element in your document.
That's it! Now, simply add CSS to style the items to match your brand.
Advanced Filtering Techniques
The TwineSocial platform is designed for extremely high performance. To achieve this, the platform is optimized to deliver contentItems
that have been previously grouped or sorted into collections. Using our Rules Engine, very advanced scenarios for filtering and retrieving content can be achieved.
For example, to display videos with the Javascript SDK:
- Login to your Admin Console.
- Create a collection called
Videos
. - Create a rule to add all contentItems containing a video to the
Videos
collection. - When using the Javascript SDK, pass in the
collectionId
for theVideos
collection.
You can build very complex rules with boolean operators, combining #hashtag, network (Facebook, Twitter, Instagram, RSS), @account, geo-location, and other content attributes.
Sample Code
The following sample pages demonstrate how to use the Javascript SDK to build different social experiences with your campaign content.
- Single Item
- Retrieve and display a single
contentItem
. - 3 Items From Collection
- Retrieve and display three
contentItems
from a specific collection. - Photo Tileboard
- Create a simple photo tileboard.
- Format & Timestamps
- Format
contentItems
, and use "3 minute ago" timestamps. - List Collections
- List collections and load
contentItems
when a button is clicked. - Infinite Scroll
- Building an "infinite scroll" view of
contentItems
from a campaign. - Featured News
- Formatting
contentItems
from a campaign for a "Featured News" area on your website. Learn how to crop images and truncate long content. - Fan Bar
- Retrieve and display your
followerItems
. Learn how to build toolbars, widgets, and other web elements that feature your official and partner social media accounts.
Methods
The following methods are available with the Javascript SDK.
getContent
Retrieve one or more contentItems
from your platform account. The onContent
and onComplete
events will fire when the function completes.
This example will retrieve the newest 20 contentItems
from the "louboutin" campaign and display them in the browser's console log window.
- request.campaign
-
string
(required) Example: louboutinThe campaign name to retrieve content from.
- request.collection
-
number
(optional) Example: 18132Optionally limits the results to a collection ID inside the
request.campaign
. - request.status
-
string
(optional) Default: active Example: modpendingOptionally limits the results to
contentItems
with a particular status. Available statuses:- active
- Only get published items
- modpending
- Only get unpublished items waiting moderation
- moderated
- Only get unpublished items that were moderated out
- brokenlink
- Only get items unpublished items containing a link to a bad image URL
- filtered
- Only get unpublished items that were filtered out by a profanity or content filter
- request.photosOnly
-
boolean
(optional) Default: false Example: trueOptionally limits the results to
contentItems
that contain a photo. - request.limit
-
number
(optional) Default: 20 Example: 10Maximum number of items to retrieve, up to a maximum of 100.
- request.id
-
number
(optional) Example: 32036227A comma-delimited list of post IDs to retrieve. Used to retrieve detail about a one or more
contentItems
.Cannot be combined with
request.collection
,request.limit
,request.status
, orrequest.offset
. - request.offset
-
number
(optional) Example: 10Optionally offset the result set. Used for pagination.
- options.events.onContent
-
function(data)
(optional)A callback function called when the request completes. The
data
parameter contains the complete response body in JSON format.
getFollows
Retrieve followerItems for each social media network that this campaign follows and/or promotes. Use this to build "Follow Us" applications, showcasing your official and related Facebook, Twitter, Instagram and other social accounts.
Follower counts for each social media account are updated every 24 hours.
The onContent
and onComplete
events will fire when the function completes.
This function call will retrieve followerItems
for social media accounts that this campaign follows and/or promotes, and display them in the browser's console log window.
- request.campaign
-
string
(required) Example: louboutinThe campaign name to retrieve content from.
- options.events.onContent
-
function(data)
(optional)A callback function called when the request completes. The
data
parameter contains the complete response body in JSON format.
getPromoted
Retrieve a JSON object for promoted content items from your platform account. The onContent and onComplete events will fire when the function completes.
This function call will retrieve promoted content from the "louboutin" campaign and display them in the browser's console log window.
- request.campaign
-
string
(required) Example: louboutinThe campaign name to retrieve promoted content from.
- request.limit
-
number
(optional) Default: 20 Example: 10Maximum number of items to retrieve, up to a maximum of 100.
- request.offset
-
number
(optional) Example: 10Optionally offset the result set. Used for pagination
- options.events.onContent
-
function(data)
(optional)A callback function called when the request completes. The
data
parameter contains the complete response body in JSON format.
listCollections
Retrieve a JSON object for collections for a specified campaign in your platform account. The onContent event will fire when the function completes.
This function call will retrieve a list of collections from the "louboutin" campaign and display them in the browser's console log window.
- request.campaign
-
string
(required) Example: louboutinThe campaign name to retrieve collections from.
- options.events.onContent
-
function(data)
(optional)Callback function called when the request completes. The
data
parameter contains the complete response body in JSON format.
More questions? Search the Knowledge Base, or ask in the Community Forums.
renderContent
Retrieve one or more contentItems
for a specified campaign, and append the results to the document.
This example will retrieve the newest 3 contentItems
from the "louboutin" campaign and append them to the "testimonials" DIV element in your document.
- request.campaign
-
string
(required) Example: louboutinThe campaign name to retrieve content from.
- request.collection
-
number
(optional) Example: 18132Optionally limits the results to the collection ID
- request.id
-
number
(optional) Example: 32036227A comma-delimited list of post IDs to retrieve. Used to retrieve detail about one or more
contentItems
.Cannot be combined with
request.collection
,request.limit
,request.status
, orrequest.offset
. - request.offset
-
number
(optional) Example: 10Optionally offset the result set. Used for pagination
- request.status
-
string
(optional) Default: active Example: modpendingOptionally limits the results to items with a particular status. Available statuses:
- active
- Only get published items
- modpending
- Only get unpublished items waiting moderation
- moderated
- Only get unpublished items that were moderated out
- brokenlink
- Only get items unpublished items containing a link to a bad image URL
- filtered
- Only get unpublished items that were filtered out by a profanity or content filter
- request.photosOnly
-
boolean
(optional) Default: false Example: trueOptionally limits the results to
contentItems
that contain a photo. - request.limit
-
number
(optional) Default: 20 Example: 10Maximum number of items to retrieve, up to a maximum of 100.
- options.target
-
string
(optional) Default: twine Example: testimonialsThe ID of the parent element in your document to append results. If you do not supply a element ID, items will be appended to the DIV element "#twine."
- options.includePromoted
-
boolean
(optional) Default: false Example: trueOptionally, include any promoted or pinned posts in position within the results.
- options.display.imageCssClass
-
string
(optional) Example: img-polaroidAdd this CSS class to images in your items. Separate multiple CSS classes with a spacebar. Useful when using bootstrap or other platforms.
- options.display.tileCssClass
-
string
(optional) Example: twine-itemAdd this CSS class to each item. Separate multiple CSS classes with a spacebar.
- options.display.dateFormatString
-
string
(optional) Example: dddd, MMMM DoFormat the date/time, using formats available in the Moment.js library.
- options.events.onContent
-
function(data)
(optional)Callback function called when the data arrives. The
data
parameter contains the complete response body in JSON format. If you define this function, you'll need to render and append each item to your document. - options.events.onComplete
-
function(data)
(optional)Callback function called when the items have been appended to the document.
- options.events.onRenderContent
-
function(contentItem)
(optional)A callback function that receives a
contentItem
object and returns an HTML string. Define this function if you want to control the HTML structure of your items. Your function must return an HTML string that the SDK will append to your document.When writing your own callback function,
contentItems
for Tweets may contain URLs encoded in a specific format designed to help you conform to the Twitter Display Requirements. This article describes how to decode and format Tweets containing URLs.
renderPromoted
Retrieve promoted contentItems
from your platform account and append the results to the document.
This function call will retrieve the newest 3 promoted contentItems
from the "louboutin" campaign and append them to the "promoted" DIV element in your document.
- request.campaign
-
string
(required) Example: louboutinThe campaign name to retrieve content from.
- request.collection
-
number
(optional) Example: 18132Optionally limits the results to the collection ID
- request.limit
-
number
(optional) Default: 20 Example: 10Maximum number of items to retrieve, up to a maximum of 100.
- request.offset
-
number
(optional) Example: 10Optionally offset the result set. Used for pagination
- options.target
-
string
(optional) Default: twine Example: testimonialsThe ID of the parent element in your document to append results. If you do not supply a element ID, items will be appended to the DIV element "#twine."
- options.display.imageCssClass
-
string
(optional) Example: img-polaroidAdd this CSS class to images in your items. Separate multiple CSS classes with a spacebar. Useful when using bootstrap or other platforms.
- options.display.tileCssClass
-
string
(optional) Example: twine-itemAdd this CSS class to each item. Separate multiple CSS classes with a spacebar.
- options.events.onContent
-
function(data)
(optional)Callback function called when the data arrives. The
data
parameter contains the complete response body in JSON format. If you define this function, you'll need to render and append each item to your document. - options.events.onComplete
-
function(data)
(optional)Callback function called when the items have been appended to the document.
- options.events.onRenderContent
-
function(contentItem)
(optional)A callback function that receives a response
contentItem
and returns an HTML string. Define this function if you want to control the HTML structure of your items. Your function must return an HTML string that the SDK will append to your document.When writing your own callback function,
contentItems
for Tweets may contain URLs encoded in a specific format designed to help you conform to the Twitter Display Requirements. This article describes how to decode and format Tweets containing URLs.
trackEvent
The trackEvent() function is optionally used to record an engagement event for a specific content item. Engagement data is visible in the Analytics Dashboard
Best Practices
Adhere to these best practices to capture the most meaningful data in your Analytics Dashboard.
- Call the trackEvent() function with the
play
eventType each time a video item is played. - Call the trackEvent() function with the
like
eventType each time a Facebook Like intent is initiated. - Call the trackEvent() function with the
tweet
orretweet
eventType each time a Tweet or Retweet intent is initiated.
This function call will record a click for a content item.
- request.campaign
-
string
(required) Example: louboutinThe campaign name to record the event against.
- request.eventType
-
string
(required) Example: playThe event type to record for a content item.
- view
- Record a "View" action for the specified content item.
- like
- Record a "Like" action for the specified content item.
- favorite
- Record a "Favorite" action for the specified content item.
- tweet
- Record a "Tweet" action for the specified content item.
- share
- Record a "Share" action for the specified content item.
- retweet
- Record a "Retweet" action for the specified content item.
- pin
- Record a "Pin" action for the specified content item.
- play
- Record a "Video Play" action for the specified content item.
- request.id
-
number
(required) Example: 2536475The ID number of the content item to record the event for.
- options.events.onComplete
-
function(data)
(optional)Callback function called when the event has been completed.
showPostCreator
The showPostCreator()
function is used to show the TwineSocial post creator for any account with the Post Creator activated.
This function call will open the Post Creator Modal for your campaign.
- campaign
-
string
(required) Example: louboutinThe campaign name for which to show the Post Creator.
- collections
-
array
(optional) Example: [234324,35353]A an array of ids for
collections
to associate with all posts created in the generated post creator.When including
collections
in a showPostCreator call, double check that you are using valid ids. If you are not, your viewers will not be able to save posts created by the generated post creator.
Object Reference
The following objects are used in the Javascript SDK. All objects are in the JSON format.
contentItem
The contentItem
object represents an individual content item from your campaign, such as a Facebook Page post, a Tweet, or an Instagram post.
{ "id": 31098100, "media_key": "873903219015770454_11285087", "feed_id": 78651, "from_user_name": "louboutinworld", "from_full_name": "Christian Louboutin", "profile_url": "https:\/\/instagramimages-a.akamaihd.net\/profiles\/profile_11285087_75sq_1363347869.jpg", "media_type_id": 2, "perma_link": "pwe-marked-the-first-year-of-o", "source": "Instagram", "votes": 31477, "status": 1, "created_at": 1418397360, "title": "", "description": "We marked the first year of our Aoyama Boutique in Japan with a pair of exclusive new shoes!", "target_url": "https:\/\/instagram.com\/p\/wgulj5gWFW\/", "image_url": "https:\/\/scontent-b.cdninstagram.com\/hphotos-xaf1\/t51.2885-15\/10817899_671484659636631_695742053_n.jpg", "image_height":800, "image_width":800, "resource_url": "", "is_retweet": false, "network": { "id": 1, "brand_url": "https:\/\/instagram.com", "css_class": "instagram", "name": "Instagram" }, "layout": { "id": 1, "name": "Full", "css": "layout-full" }, "has_body": false, "cta":{ "cta_id":430, "name":"Hat", "button_text":"Buy the Hat!", "target_url":"http://amazon.com/hat", "has_detail":true, "detail":{ "image_url":"//static.twinesocial.com/uploads/jasonbourne/27149cd50d30a07bd0d329f73012c4e78ec99053.png", "description_text":"Lorem ipsum dolor sit amet Noah, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim venia m, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Duis aute i" } } }
- id
-
number
(required)The globally unique numeric identifier for this content item in the TwineSocial data store.
- media_key
-
string
(required)The globally unique string identifier for this content item (usually the original Tweet ID or Facebook Post ID). Used to correlate a post with third-party tools.
- from_user_name
-
string
(optional) Example: twinesocialThe content author's username. It is not preceded by the @ symbol.
- from_full_name
-
string
(optional) Example: Mark HansonThe content author's full name, if known.
- network_id
-
number
(required) Example: 1A numeric identifier corresponding to where this content was discovered.
- profile_url
-
string
(optional)The author's avatar image.
- source
-
string
(required) Example: InstagramThe name of the community or network where this content originated from.
- votes
-
number
(required) Example: 25The sum of the number of votes/likes this content acquired at the time it was ingested.
- created_at
-
timestamp
(required) Example: 1417844936The epoch timestamp for when this content was authored.
- title
-
string
(optional) Example: She's Just Our Type!Content title
- description
-
string
(optional) Example: We have no more to say.Content description
- target_url
-
string
(optional) Example: https://instagram.com/p/wQQ1wrsvSR/A URL corresponding to the original source location
- image_url
-
string
(optional) Example: https://www.msnbc.com/image.jpgA URL for the primary photo for this contentItem
- image_width
-
number
(optional) Example: 640The width in pixels of the primary photo for this contentItem.
- image_height
-
number
(optional) Example: 480The width in pixels of the primary photo for this contentItem.
- resource_url
-
string
(optional)A URL pointing to the video stream
- is_retweet
-
boolean
(optional) Default: false Example: falseIndicates if this item is a retweeted.
- layout
-
layout
(required)Populated with layout details for this
contentItem
- network
-
networkItem
(required)Populated with a
networkItem
object for thiscontentItem
. - has_body
-
boolean
(required) Default: false Example: falseIndicates whether this item has a Post Body. You must access the Post Body separatley through the
Post Body
endpoint. - cta
-
ctaItem
(optional)Populated with Call To Action details for this
contentItem
. - related
-
contentItem
(optional)Populated if this
contentItem
is in reference to a relatedcontentItem
. For example, if you comment on a Facebook post, your comment will appear as acontentItem
; the original Facebook post will appear as a relatedcontentItem
.
Additional fields may appear in a contentItem. However, developers should not rely on them; use them at your own risk. They may be dropped at any time without prior notice, or a version change to the API.
followerItem
The followerItem
object represents Follower properties for a campaign.
{ "id": 2941, "type": "others", "username": "christianlouboutinshoes", "name": "Christian Louboutin", "cssclass": "instagram", "subtitle": "Follow on Instagram", "profile_url": "https:\/\/instagramimages-a.akamaihd.net\/profiles\/profile_19191702_75sq_1326342209.jpg", "objectId": "19191702", "network": { "id": 5, "brand_url": "https:\/\/www.instagram.com", "css_class": "Instagram" }, "likes": { "count": 123254, "subscriber_phrase": "followers" }, "is_active": true }
- id
-
id
(required)The globally unique numeric identifier for this followerItem.
- type
-
string
(required) Example: othersIndicates whether this item represents an official brand account (ours) or a followed/promoted account (others).
- username
-
string
(required) Example: louboutinThe network-specific username for this item. For example, if the Twitter account name is @twinesocial, you'll see twinesocial in this field.
- network
-
networkItem
(required)Contains network-specific properties for this follower.
- likes.count
-
number
(required)The number of likes/followers that this account has. This value is updated daily by the TwineSocial platform.
- likes.subscriber_phrase
-
string
(required) Example: fansThe unit of measure for
likes.count
. - subtitle
-
string
(required)A text subtitle
- profile_url
-
string
(required)The follower's avatar image.
- objectId
-
number
(optional)The network-specific ID for this follower. Typically corresponds to their Facebook,Twitter, Instagram, or other social network userID.
- is_active
-
boolean
(required) Example: trueIndicates if this follower profile is active or not. Monitor this field to detect OAUTH token failures.
Additional fields may appear in a followerItem. However, developers should not rely on them; use them at your own risk. They may be dropped at any time without prior notice, or a version change to the API.
networkItem
The networkItem
object describes a social media network.
{ "network": { "id": 1, "brand_url": "https:\/\/instagram.com", "css_class": "instagram", "name": "Instagram" } }
- id
-
id
(required) Example: 3The unique numeric identifier for this social media network.
- brand_url
-
string
(required) Example: https://instagram.comThe official homepage for the social media network
- css_class
-
string
(required) Example: instagramA css_class name which uniquely identifies this network. Used when building UI components. This text string will always correspond with a brand icon available in the Font Awesome library.
- name
-
string
(required) Example: InstagramA string which uniquely identifies this network.
Additional fields may appear in a networkItem. However, developers should not rely on them; use them at your own risk. They may be dropped at any time without prior notice, or a version change to the API.
Event Reference
The following events are used in the Javascript SDK.
onReady
Fired when the SDK is loaded and ready to be used.
onComplete()
Fired when a function call has completed. Used to manipulate content after it has been appended to the targetDiv
.
onContent(data)
Fired when data arrives from the remote server. Used to manipulate content before it has been appended to the targetDiv
.