SocialSamba API
The SocialSamba API Tutorial
How easy is it to integrate SocialSamba stories into your website? Well, that depends. If you just want a story that plays within your website then you can use our embed code, and it’s no harder than putting a Youtube video into your website. If you want deeper integration, such as the ability to trigger different actions within your website depending on what is happening within the story, you want to integrate our JavaScript API into your website. It gives you the ability to trigger parts of the story and for the story to trigger things on your site. This blog post will walk you through the steps of integrating the JavaScript API into your website.
Step 1.
Create a social story on SocialSamba.com. Make sure your story has at least one character, multiple posts, and also make sure it is properly published. You can create your story at the following URL: http://www.socialsamba.com/saga/index.html?s=new
Step 2.
After you create your story and publish it. Go to the publish tab and click on “See story on SocialSamba” button. Once you are on the read page take a look at the URL in your browser. It should look something like:
http://www.socialsamba.com/read/the_tweet_in_trafalgar_square
Each story in SocialSamba must have a unique title that is required inside the API. In the above example it is the characters after the final forward slash “choose_your_own_pokemon_adventure”. This title will be used anywhere in the API that makes reference to parameters called “story_title”.
Step 3.
Create your page and make a <div> that you want to bind the story feed into. Inside that page you need to first include the socialsamba javascripts into your header. The following two lines will do that for you:
<script type=”text/javascript” src=”http://www.socialsamba.com/assets/feed.js”></script>
<script type=”text/javascript” src=”http://www.socialsamba.com/javascripts/samba.js“></script>
Note: We strongly recommend you download the samba.js file and view it in a text editor. It contains detailed documentation for each of the available SocialSamba API calls.
Step 4.
Initialize the SocialSamba API within your page with the following line:
samba.init({app_title: ‘saga’);
Note: ‘saga’, is the app used for any stories created inside SagaWriter. If you are working in a premium production, contact SocialSamba to get your own app_title for initialization.
Step 5.
Log into the SocialSamba website from your page with this following line of sample code:
samba.ready(function(){
samba.loginDomain(‘http://nt0.ggpht.com/news/tbn/JPUO8EWLKk1FQM/1.jpg’, ‘Cheryl’, ‘female’, ‘cheryl@socialsamba.com’, ‘1’,
loginDone, loginFailed);
});
Two important things are happening here. The first is that we are making use of the samba.ready function. This method ensures that initialization of the SDK is complete for executing the function parameter.
The inner function contains the samba.loginDomain call. This is used for domains that have their own users that they want to pass to SocialSamba. The parameters are the avatar url, the user’s first name, the user’s gender, the user’s email, the relying party id (your unique identifier for that user), a function parameter for when the login completes, and a function parameter if the login fails.
We use the email and the relying party ID to uniquely identify users in our system. So, you must make sure they are both unique for every user passed to SocialSamba.
Step 6.
Load the feed into your page. The moment of truth has arrived; it’s time to load the story feed into your page. Use the following line to load the feed into your page:
samba.loadFeed(‘.action-feed’, ‘the_tweet_in_trafalgar_square’, function(){
// do something here
});
The samba.loadFeed API is very simple. The first parameter is a selector for the div you want the feed loaded into. The second is the “story_title” we discovered in Step 2 of this tutorial. The third parameter is a function that you want called after the feed is fully loaded.
Step 7.
The story you created in SagaWriter should now be playing back inside your web page. But, there is much more you can do with the API. Here are a few examples of things that you might want to have a closer look at inside samba.js:
samba.swapFeed(‘story_title’, callbackFunction)
This API allows you to switch one story in your page for another from SocialSamba. Just pass in the story_title of the new story and it will swap the current feed out for the new one.
samba.pauseFeed();
samba.playFeed();
These two are pretty self explanatory. If you need to pause the feed while the user is doing something else on your site you can do so via this API. Play restarts it playing after you are done pausing.
samba.getPropertyState
samba.setPropertyState
samba.subscribeProperties
These three are reserved for premium customers only. They are very powerful in allowing you to set properties which can trigger branches in the story to start playing. And, they allow you to listen for properties that are set in the story so that they can trigger things to happen or be enabled within your page.
Conclusion
We hope you enjoyed learning a bit about the SocialSamba JavaScript API. It make integrating SocialStories into your page a breeze. Drop us a line if you want to use it for a premium production. We would be happy to provide you with assistance in your next project.
Cheryl Opletayev, CTO
cheryl@socialsamba.com
