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

The Birth of a Platform

When we started out building the SocialSamba platform, we intended for it to be a service that others could plug into through an API.  But, as most platforms start, we had to cut our teeth on enough customer projects that we finally understood what is really required of an API.  You start with a “best guess” at what is necessary, but ultimately those first 10 customers are going to steer you where you need to go.

As we moved through those customers we built our own internal API’s that we would use for each customer implementation.  They were raw and a bit clunky.  And, they almost always exposed too much of the underlying system to the application developer.  That was great for us internally.  It helped immensely with debugging, and it gave us access to some of the constructs that felt familiar to the core data models.  But, it was not an API that was constructed for outside consumption- too much of a Kitchen Sink API.

Fortunately, the “Kitchen Sink API” is now obsolete.  Our most recent “premium production” we did with USA Network forced us to take our API and make it ready for general consumption.  They hired a third party integration team that was going to take our API and build a website around it (along with a bunch of other very cool stuff for their project).  Needless to say, we were ecstatic that we are finally at the point where we could truly become a platform.  But, it also meant doing some hard work to narrow down our API into a simple and easy to use set that would allow people to innovate on top of what we have built.  Now that the project has released, I can say that our goals were achieved.

Stay tuned for our next blog post, which will give a mini tutorial of how to integrate a social story into your website.

- Cheryl (cheryl@socialsamba.com)

Let’s Go Camping - Why We’re Excited To Participate In Turner’s Media Camp

At one point in my life, I was a fearless Boy Scout who loved everything about camping.  The metal plate full of fire-charred food, the sunny days fishing (and playing with worms), and the freedom from showering made for a little slice of heaven.

Oh how I’ve changed.  I got my Eagle Scout, went off to college, and eventually moved to California.  And somewhere in there I became as soft as cream cheese.  If I really had to go for a week without my Peet’s coffee and internet addictions I probably could, but I’m ashamed to admit I don’t think I’d enjoy it like I enjoyed those free days as a boy.

So, I had sort of resigned myself to not being a “camper” any more, until I bumped into some guys at SXSW in March who said they had the camp just for me.  Media Camp!

And today, I’m very excited to announce that SocialSamba will be participating in Turner’s Media Camp this summer.  I’m a camper again, and I still get my coffee and internet!  I couldn’t be happier.

Wade Roush from Xconomy did a great job explaining what Media Camp is, and tried to also explain why Turner is doing it.  ”Hedging against a digital future” is one way to look at it I guess, but Turner’s strategy is actually far more about innovation than hedging to me.  Scared companies hedge.  I see Turner as a leader in the space, not one of the cowards.  And even if they wanted to hedge, a Media Camp would not be a very effective way to do it.  Innovating is messy and hard, it requires you to be satisfied with failure and learning as a possible outcome.  Hedging is buying insurance because you’d rather not do that hard work.  I see Turner as leading a new trend here, and I suspect more media companies will be giving it a try.

Part of SocialSamba’s DNA is trying new things.  We’re innovators, first and foremost.  We’re defining a new kind of storytelling, we jump into new StoryHack events with both feet, and we’re the people who play Scramble with Friends .. without our friends.  So, the opportunity to be part of the inaugural class for Media Camp was exciting because we believe in the innovation.  But there’s more.  Much more:

• Mentors from across Turner’s massive, diverse brands who can provide perspective and guidance on not just our platform and technology, but also our business model.
• Other smart startups that we can learn from.  (We’re meeting for the first time next Monday, over dinner, but just stalking through their websites and leaders on LinkedIn, I’m excited.)
• A Demo Day in September with the exposure Turner can drive.

And the excitement is mutual.  Balaji Gopinath, Turner’s VP of Emerging Technology said, “Turner has always been a leader in the media space through our original content and programming. Storytelling is part of society’s social fabric; and SocialSamba’s storytelling technology is an exciting and unique platform that extends a media company’s reach into the social web. We are very pleased to have SocialSamba be part of the inaugural Media Camp Academy and look forward to exploring how we could create some amazing social stories with our programs and networks.”  Amen.  Let’s go create!

This announcement caps off another busy week at The Samba.  It started with an excellent article written about our platform in Variety.  Then we launched our latest social story with MTV (check out Teen Wolf: The Hunt and what the fans are saying about how much they love it).  The rest of the week and weekend will be devoted to putting the finishing touches on another very cool social story launching next Monday (can’t say any more than that just yet …).

Particular thanks to Balaji Gopinath and David Austin for including us in the Media Camp program.  Their leadership at Turner and in the digital space in general is really inspiring.

Okay, time to pack my bag.  I’m going to camp!

My StoryHack Experience

72 hours after the 36 hour sleepless odyssey that was StoryHack: Beta, and my body is still feeling a bit sleep deficient.  Which feels a little strange, because I’m sure I used to do weekend-long coding-benders like this all the time during my first startup 13 years ago without any impact … right?  “Sure,” says my indignant body, “13 freaking years ago!”  Sigh.

But no “you’re-an-old-ass-man” realization can get me down today.  I’m still feeling the good vibes and warm glow of the StoryHack.  Which also compels me to capture some thoughts and realizations from the event.  (Note: these are all my personal thoughts.  I’m guessing other’s results varied, even within the SocialSamba team.)

First observation, at the 30,000 foot level: the overall weekend was a huge, huge, huge success.  A few specific things that went well:

• The stories themselves (each team’s results) were probably the most obvious sign of the success.  The 7 stories that were created were diverse, deep and utterly entertaining.  Every single one left me thinking “Holy crap, that happened in 36 hours?!”  (And I was there all 36 hours!)
• No teams quit, dropped out, or melted down.  As a participant in other hackathons, this is actually kind of amazing.  Success is getting as many teams as possible across the finish line, which almost never means all of them.
• The team at the Film Society was a huge success factor.  We had power and wifi in abundance, a beautiful theater to present in (and nap in), and high quality food that just never quit.  Space matters when you want innovation, and this was a huge plus.  (Huge dap to Matt Bolish and the crew!)

Then there were a couple specific things that I think went REALLY well:

• Mike and Aina.  Period.  They took a huge risk, worked hard to bring this to reality, and followed through with great communication and hands-on participation.  They recruited some amazing mentors and savvy judges, too.  We were so lucky to have them at the helm.  It was technically labeled a “beta”, but there was nothing beta about this event, thanks to their effort.
• All of the participants on the teams were f-ing amazing.  Not just brilliant and creative people, but good and collaborative people.  And the energy.  Oy, the energy.  The participants never stopped, never gave up and never fought.  Maybe I’ve been to the wrong hackathons in the past, but I’ve never been to one without a fight over direction in at least one of the teams.  Think “group week” on American Idol as another example - there’s always a melt down.  Not here.  And every participant at StoryHack was given an NYC branded stress ball in their swag bag … how the hell did those not end up being projectiles?!  Simple, good people.

Of course, no stream of reflections like this would be complete without some thoughts on how we could improve the experience.  I’m only bringing these up because I know based on the success of this event that we’re going to be doing this more (ALOT more), so maybe these ideas can help in the planning of the next one.  My humblest of humble suggestions:

• I think we should cover the walls in paper next time, and encourage teams to use the paper for planning, designing and playing tic-tac-toe.  I remember a few times when teams were scrambling for paper to do some planning, and really needed something more than a 8.5x11 sheet.  White boards could work too, but for just 36 hours, I love the permanence and oooh-look-what-they’re-doing aspects of the papered walls.
• The judges should give feedback.  At the very end, after they had determined the winner, it would have been awesome for the judges and the teams (and the mentors) to have a conversation about the stories.  They don’t have to tell us the deliberations, just give us their impressions.  Those judges and mentors were amazing, and seeing the stories through their eyes would have been super valuable for the teams I think.
• I found the variety of the results to be a huge plus for me as a story-participant, but also a real challenge in determining a “winner”.  I was really torn when it came to handing out my (non-existent) “Aaron Award” for my personal winner because I enjoy both apples and oranges.  I’m just terrible at comparing them.  I realize most storytellers would probably barf at a constraint like this, but I wonder what it would have been like if someone had defined a kick-ass foundation of a story world - some characters, some background, and a “start” of the story - and then let the teams go off and finish it and express that finish however they wanted.  I would bet, based on this experience, that we could get a “celebrity” storyteller to create that start …
• Finally, I wonder if it wouldn’t be better if the results were oriented beyond a 15 minute presentation.  Maybe, at the end of the 36 hours, each team would be asked to give up a URL that was the rabbit hole for their story, no presentation necessary.  Then, everyone (and I mean everyone) would have a chance to come in and actually experience the stories, over 24 hours.  We could comment on them, share them, and really get into them.  I think that is one of the things that has made my previous hackathon experience so interesting is that the result is not a presentation.  The result is a URL, and each team is judged on a first-hand experience with what they created.  This would, of course, limit the kinds of results that could be created in 36 hours, but I think focusing the teams on creating something that anyone can experience is a good thing.  (Or maybe I’m just dreaming of getting in a nap between the end of the event and the public awards presentation.)

I also had a couple people ask why SocialSamba participated, and why we sent 3 people to pricey NYC for the weekend (something we tight-wad early-stage start-ups never do).  The answer is easy, we got more out of the experience than we put in, by about an order of magnitude.  Here’s why:

• In the first 18 months of our company, we’ve produced 5 really compelling stories with some top-shelf creative teams from companies like USANetwork, Warner Bros and MTV.  In the StoryHack, we worked with 7 new creative teams that were every bit as good and produced content just as compelling.  All at once.  Start-ups dream of accelerators like that.
• The participants identified some new bugs in our platform.  Ain’t no shame in it.  We also found some very interesting new features.  We love this kind of real-time testing and fixing.
• Cheryl and Kirk have been one of SocialSamba’s best kept secrets, but they’re a secret no more.  They rocked the hack.  I feel personally blessed to have this team in the trenches with me, and I’m so proud to see the well-deserved recognition they got from rolling up their sleeves with the teams.

Okay, enough reflection.  Time to get back to making it so 15 year old girls can friend werewolves … I love my job!

Super users vs. Casual users

From the very earliest days we have thought hard about how to create a great user experience for all users in scripted social networks.  Preferably one that exceeds their expectations of existing social networks.

One of the most important concepts we have is the feeling of movement for users to keep them engaged without overwhelming them.  Another challenge is the different kinds of users.  There is the Super user who checks in 10 times a day, or possibly even leaves a tab open all day with the social network running.  And then there are the more Casual users that come back only once a day, or every couple days.  We’ve solved these problems in novel ways (patent pending!), and we wanted to share some of those thoughts with you.

To properly handle the different types of users we decided early on that Super users should see more content than the Casual users.  Sounds easy right?  Well, how do we expose that in a way that makes it easy for authors to create stories that cater to both?  Authors are already being challenged to write multiple stories within a story (via our branching/choose your own adventure capabilities).  Now we are asking them to write different stories for each of the user types?  No, not really.  What we do instead is tell them to write the “required” scenes in the story.  Then when they are done with that, we go back and ask them to write the “optional” scenes in the story.  Depending on different user behavior, some users will see the optional scenes (ie.. the Super users), but all users will see the required scenes. By having both types of scenes, the plot can still play out, but with differing amounts of content for each user.

Keeping users actively engaged in a social network is a very different problem.  We like to have “movement” in the feed whenever the user logs onto the network so that they can feel like the story is actively moving.  For this, we have created the concept of “real time” scenes in the system.  These are scenes that are scheduled to play within a certain time range, but will kick off immediately if the user is currently logged on to the social network.  These scenes are great for providing that real time “movement” that we know the user can engage in.  

But, we can’t have a story with all “real time” scenes.  That would provide the user with a burst of activity, but the rest of the day would be empty.  So, In order to preserve this we created “fixed time” scenes, which happen at a particular time each day.  For instance, at 8am tomorrow morning something will happen in the story and there will be a flurry of posts/comments related to that plot development.  This is great because it gives the user a reason to return so that they don’t miss the activity.  Especially if the author tells them to check in at that time tomorrow!  But, it also creates a bit of “missed opportunity” for the user that they can feel remorse about if they don’t check in at that time.

Finding a proper balance between these two types of scenes is critical in story development.  To many “fixed time”, and users will not feel like active participants in the story.  To little “real time” and the users will not feel the urgency to check into the network at all hours of the day (or keep their browser open all day!).  Hashtag Killer is a great example of a story that balances all of the above concepts very well, and it definitely shows in the amount of engagement that users have put into each episode.

All of these scene types are currently available in our Premium scripted social networks.  In SagaWriter we only support “required” “real-time” scenes.  But, as time goes on we are actively looking for ways to integrate these advanced features into the SagaWriter without overwhelming our authors.  Stay tuned for more thoughts on writing great scripted social networks.

Happy Authoring.

-Matthew

Perceivable Determinism in Social Interaction: Why you might want interactive characters to be more predictable than people. (Part 2)

In Part 1 we talked about how limiting and directing choices in interactive stories lets the storytelling shape the player’s character. The case still remains open on what players find most engaging and rewarding.

Do players want to be able to log on to a forum and find out the exact steps they should take in order to win the favor of their favorite character?

The infamous Final Fantasy VII date scene that inspired over 9000 FAQs.

Or, would a more “realistic” system that takes into account uncontrollable variables, like random character mood or attention to the weather result in a more entrancing, attractive experience? That’s how real people work, after all.

It’s a tricky coin. I would be mortified if a beloved character yelled at me the same way a mysteriously stressed out co-worker does. I immerse myself into stories for enjoyment and enrichment, not a dose of absence of control that steers me even closer towards learned helplessness. Moreover, the way we can put on hats, becoming more charismatic and socially felicitous than we manage with our own words and gestures, is undeniable soothing and rewarding. Players are able to transform from a sweatpants-wearing, couch-sitting mortal into a taciturn and eloquent monk with the help of the storyteller.

Dating simulators, experiences where players can woo digital love partners, are quite popular in Japan but have not quite caught on in America. Atlus, a Japanese gaming company, recently brought the simulator-like game Catherine http://www.catherinethegame.com/ on shore.

The protagonist of ‘Catherine’ sitting with the cute blonde love interest.

In this game, the player can chose between many actions that result in winning favor with one woman, at the expense of another, through dialogue scenes interspersed between sadistic puzzle games. The consequences of every choice rises or lowers the affection of two women, explicitly showed to the player through a “karma meter.”

The “Karma Meter” appears to the right whenever the player says something that influences which girl likes him more.

I’ll be the first to admit that I wish I had one of these in middle school. I might have been more popular if I was able to quantify how something I said affected those around me. Golly, I might have even gone on a date if I could have found a good FAQ.

In Star Wars: The Old Republic, units of character affection are shown to the bottom left after dialogue choices

Many recent games that are role-play heavy have adopted the method of displayable “units of affection”, including Dragon Age,Star Wars: The Old Republic, Harvest Moon, and .hack. Let’s be clear that this is no technical limitation: artificial intelligence techniques like Markov Chains and Machine Learning have been employed to solve related problems for decades. Moreover, these “affection unit” systems would work without displaying these numbers to the user; interactive social experiences purposefully chose controllability over immersion.

Perceivable Determinism in Social Interaction: Why you might want interactive characters to be more predictable than people. (Part 1)

Interactive characters are now familiar friends; from the earliest text based MUDs through to be able to have a digital spouse in modern video games, we’ve been making 1s and 0s laugh, flirt, adventure, and cry with us as long as we’ve known how.

While today’s bots are not yet passable for humans, modern storytelling through interactive stories and games continue to break ground in how people interact with characters. It turns out we’re not very picky clients; anyone who remembers the 128 pixels displaying a hungry, unhappy tomogatchi can tell you that guilt and anguish are easy to electronically instigate. Our inherent tendency toward anthropomorphism allows us to effortlessly slip into digital drama. In short, Scully, we want to believe.

Storytelling, traditionally a deterministic medium, is most prevalent in interactive experiences as sets of options and results that create a tree-structure, like a choose your own adventure book.

Most of the time a player encounters these branches naturally through action, such as deciding to go to the mall over staying at home, which unlocks a distinct plot-line or content. Interaction with characters is a harder issue, and is usually dealt with as a choice presented to the user.

The critically lauded Mass Effect game by Bioware gives the player dialogue choices. Depending on what the player says, the characters will act differently towards the player and the plot modulates. These choices influence everything from coldly deciding to shoot someone at gunpoint to nervously electing to comfort and kiss a companion in hopes you’ll get to bring them to bed. While the choice system looks kludgy and disruptive at first glance, it becomes second nature and has the bonus of granting the storyteller power to shape the player’s character.

While this might be restricting for the most creative of role players, it allows for a true alternative to the silent protagonist that permits shared cultivation of an identity in an alternate world. Is YOUR character a badass cowboy in the story? The storteller is probably not going to give you a choice to open a cupcake shop.

You just don’t look like the cupcake type, anyway.

(The storyteller is also probably not going to let you woo the heroine by talking about your pog collection. Sorry. They’re cool, really.)

Now that we’ve talked a bit about authors and storytelling, stay tuned for Part 2, where we’ll be going in to what users, readers, and players get out of controllable social interactions in stories.