The Synaptop API

Synaptop's API allows you to deploy your web application to multiple platforms and take advantage or Synaptop's unique live colaboration tools. The Developer application is released on October 28th 2011 and we will be adding the update to the Synappstore the week of November 1st so you can start putting your apps in the Synappstore. In the mean time, you can begin writing your apps using the API. Getting started with the Synaptop API is easy:

Sample App

You can download a sample app by clicking the Download Now button below:

Download Sample App now

Your App's Settings

Launch URL

Your launch url is where Synaptop loads your application from. Set this url to your initialization script on your server.

Example:
http://mysite.com/my-synaptop-app/index.php
http://mysite.com/
http://www.mysite.com/synaptop-app.asp

Site Domain

Your site domain is important, allowing Synaptop to identify applications and ensure that it is communicating with only trusted sites. Every message between your site and Synaptop requires that this domain matches the domain the request is coming from so please ensure that it is accurate.

Example:
synaptop.com
myapp.com
www.myapp.com

Other Settings

Approved

Displays that approval status of your application. If your application is approved, it will appear in the Synappstore.

Icon Url

A url that points to the icon for your application. It should be at least 64x64 pixels so that it appears correctly on higher-resolution displays. It must be in PNG format.

Example:
http://www.myapp.com/icon.png

Mobile Enabled

Mobile development for the Synaptop API is being rolled out the week of November 1st. If your application is mobile-ready, change this value to true. Mobile applications should be formatted for displays on IOS/Android devices and be optimized for a touch interface. A useful tool to help you get started developing mobile interfaces can be found here:

http://jquerymobile.com/

First Launch

Once you have completed the setup for your application, you will need to get your server ready to launch your app. Below is a "Hello World" style example illustrating the basic framework of a Synaptop application.

To be able to access the Synaptop API from your application, you must include the Synaptop API script in the HEAD section of your startup page (the example below uses jQuery to call synaptop.loaded() when the document is ready. You can use any other framework to accomplish this.

<script type="text/javascript" src="http://www.synaptop.com/js/synaptop.api.js"></script> <script type="text/javascript"> var appId = YOUR_APP_ID; var programId = < ? echo $_GET['pid'] ? >; $(document).ready(function(){ synaptop.loaded(function(result){ if (result){ // put your Synaptop calls in here } }); }); </script>

If your launch url is http://www.mysite.com/app.php, Synaptop launches your application by loading that url inside an iframe that resides within a Synaptop window. Two parameters are passed to your application:

pid — The operating system ID of your program. Set the javascript variable programID to this value before calling synaptop.loaded()

mobile — A boolean value indicating if the user agent is a mobile device or not (this approximation is done based on the user-agent that the browser provides. It may not be entirely accurate so best practices for CSS are recommended when creating your application.

Once your application is loaded, call synaptop.loaded() to notify the operating system that your application has completely loaded.

API Functions

Once you have called synaptop.loaded() and notified the operating system that your application is loaded, you can begin accessing the native functionality of the Synaptop Operating system. Below are the various function calls you can make on the Synatop system:

.loaded(callback)

Description: Call the loaded function once your application has loaded to register it with the Synaptop Operating System.

synaptop.loaded(function(result){ if (result){ // Synaptop recognizes your app. You can now set your callback functions for subscribers, messages in here. // Example: synaptop.onSubscriber(function(response){ //do something with a new subscriber }); } });

.onSubscriber(callback)

Description: Set a callback function to be called when a new subscriber/follower is added to the program.

synaptop.onSubscriber(function(response){ console.log(response); });

.onDisconnect(callback)

Description: Set a callback function to be called when a new subscriber/follower stops following the current user.

synaptop.onDisconnect(function(response){ // do something });

.promptQuestion(question, questionType, callback)

Description: Use the native prompt to ask the user a question.

question
The text of the question you would like to ask the user.

questionType
The button set that you would like to present to the user. The accepted values for this are "yesno" or "okcancel". Each will provide an answer of true or false respectively.

callback
The callback function to run when the question is answered by the user.

synaptop.promptQuestion("Are you sure?", "yesno", function(response){ if (response){ // do something } });

.closeApp()

Description: Closes your app.

synaptop.closeApp();

.promptMessage(message)

Description: Use the native prompt to show the user a message.

message
The text of the message you would like to show to the user.

synaptop.promptMessage("Error: Action not allowed");

.subscriberCount()

Description: Get a count of how many people are subscribed to the current user.

synaptop.subscriberCount(function(response){ if (response > 0){ // do something } });

.userAgent()

Description: Returns the user-agent details about the client. The object that is returned will contain two properties:
userAgent — the user agent string of the client.
device — one of "iPod", "iPhone", "iPad", "BlackBerry", "Android", "unknown". If you need more specification than the options provided, you can parse the user agent string.

synaptop.userAgent(function(response){ if (response.device == 'iPad'){ // do something } });

.yql(yqlQuery, format, callback)

Description: Execute a YQL statement and get teh results back in the format of your choosing.

yqlQuery
The query you would like to execute.
Example: SELECT * FROM html WHERE url = 'http://www.cnn.com'

format
Provide the format that you want to receive the results of the query in. You can choose "xml" or "json".

synaptop.yql("SELECT * FROM html WHERE url = 'http://www.cnn.com'", "json",function(response){ // do something });

.broadcast(msg)

Description: Send a message to all subscribed/following clients.

msg
A message that you would like to broadcast to all connected clients.

synaptop.broadcast({'action':'stop'});

.broadcastRecipients(recipients, msg)

Description: Send a message to all a subset of subscribed/following clients. Each client that subscribes the onSubscriber function. You can use this information to manage the list of subscribers or you can call the getSubscribers function to get a list of client ids that are currently connected.

recipients
An array of integer ids of the clients to send the message to. The clients must be part of the current subscribers list to send a message to them.

msg
A message that you would like to broadcast to the selected connected clients.

synaptop.onMessage([1,2,3], {'action':'stop'});

.onMessage(callback)

Description: Provide a callback function to be initiated when a message is sent from another client to the local client. It is up to you to format your outgoing messages that are sent via the broadcast or broadcastRecipients function so that they are readable by the function provided to onMessage.

synaptop.onMessage(function(response){ // do something });

.getUser(callback)

Description: Get information about the current user. (Returns the name, id and profile image of the user.

callback
The function to be called when the user is returned.

synaptop.getUser(function(response){ alert(response.firstname); });

.getSubscribers(callback)

Description: Returns a list of subscriber ids.

callback
The function to be called when the file is returned.

synaptop.getSubscribers(function(subscribers){ for (var i in subscribers){ // do something } });

.getFlashVersion(callback)

Description: Get a the flash version from swfboject. More about the function here: http://code.google.com/p/swfobject/wiki/api

callback
Callback with the results of getFlashVersion.

synaptop.getFlashVersion(function(playerVersion){ alert(playerVersion.major); });

.getOnlineFriends(callback)

Description: Returns a list of the users current friends that are online:

callback
Callback function to be passed the list of friends

synaptop.getOnlineFriends(function(friends){ for (var i in friends){ // do something } });

.openFile(callback)

Description: Prompts the user to open a file and then returns the file.

callback
Callback function to be called with the file as a parameter

synaptop.openFile(function(response){ if (response.selected){ // user selected a file alert(response.name); // files full name alert(response.ext); // files extension alert(response.url); // url to access file }else{ // user pressed cancel and did not select a file } });