Widgeous Developer Getting Started Guide

Welcome to the Widgeous Developers’ Network, or more affectionately known as DevNet. Here, we hope to maintain open communication with the developers who will be building Widgeous Applications and that’s…. YOU!

So you’re wondering how to start. Well, we’ll break this down into a few parts so that it’ll be easier to digest. We’re going to assume you already have a normal Widgeous user account so we’ll skip the howto “Register for an Account”

Getting Started

  1. Basic Concept
  2. Creating a New Application
  3. Building an Application
  4. Interfacing with Widgeous
  5. Testing Out The Applications
  6. Going Live
  7. Take It Up A Notch - Submit for Review

Basic Concept

Widgeous is:

  • a unified communications platform that is ever expanding and growing.
  • the command-line for the internet.
  • a REST API-based platform for developers to expand web services to more communication devices easily and efficiently.

Creating a New Application

Before you begin, you’re going to have do a few things. Firstly, head over to the Developer Network page, log in and click “Develop”.

click “Develop”

Here you’ll find a list of all your existing applications. To create a new application, click “Create a new app”

Here you’ll need to fill some details:

  1. Nice name
    The official name for your application.
  2. Shortcode
    This will have to begin with an underscore and will actually be the keyword used for people to interact with your application.

E.g. We’ve named a sample demo application and given it a Nice Name of “Simple Demo” and a Name of “_simpledemo”.

Ok. You’re done with “Creating a new Application”.

Now on to actually building an application!

Building an Application

Builing an application is easy! Just code in your preferred language and plug it into our API!

For this guide, we’ve created an application that will do 3 things:

  1. Display a simple “Hello World”
  2. Display the values of the various variables that our API passes to you
  3. Displays a given string in reverse order.

You could of course, build more complex things because you have free play in building your application logic.

<?php
 
// You first start by isolating the POST elements
	$params =  $_POST['paramWhole'];
	$sourceId = $_POST['widgeousUsername'];
	$sourceIdAuth = $_POST['widgeousAuth'];
	$chanID	= $_POST['uniqChanID'];
	$channel = $_POST['channel'];
	$command = $_POST['command'];	
 
// Then based on the $command argument, you can call various self-define functions.  
// You can add as many, and as complex functions as you want in the function logic.
// everything that is echoed will be returned to the user.  
	try {
		if(strtoupper($command)=="HELLO"){
	    	hello();
  		}
  		else if(strtoupper($command)=="ECHO"){
  			echoDetails($params, $sourceId, $sourceIdAuth, $chanID, $channel, $command);
  		}
  		else if(strtoupper($command)=="REVERSE"){
  			reverseString($params);
  		}
  		else{
  			errorMsg();
  		}
	}
	catch(Exception $e){
		echo "Something went wrong. You can report the glitch to ask@widgeo.us and we'll try to fix it.";
	}
 
// prints a string back to the channel where the command was initiated 
function hello(){
	echo "Hello World!"; // ok, how much lamer can we get right?  
}
 
// prints the list of variables that was passed from Widgeous to the App
function echoDetails($params, $sourceId, $sourceIdAuth, $chanID, $channel, $command){
	echo "paramWhole: $params \n";
	echo "widgeousUsername: $sourceId \n";
	echo "widgeousAuth: $sourceIdAuth \n";
	echo "uniqChanId: $chanID \n";
	echo "channel: $channel \n";
	echo "command: $command \n";  
}
 
// prints a given string in reverse
function reverseString($string){
	echo strrev($string);
}
 
// does the same as reverseString() but implements session support
function reverseSession($postvar){
	$string = $postvar['session_params'];
	if(!empty(trim($string))){
		echo "The Reverse of '".$string."':\n";
		reverseString($string);
	}
}
 
// Prints a pre-define error message
function errorMsg(){
	echo "Invalid Command. Please use the following format:\n";
	echo "_simpledemo reverse This is the String to be reversed.";
}
?>
 

Ok. Now that you’re done with building the application logic, you’ll host your application at a server that's reachable to the public.

Now, it’s time to link it up with Widgeous.

Interfacing with Widgeous

My Applications

If you head back to your Applications Page, you’ll realize there are two parts you’ll need to configure.

Application Options

API Key
API key will be used when your application initiates a request to Widgeous. More details on this soon.
Nice Name
This is the name the proper name that you gave your application in Step 1.
Brief Description
This should be a shorter, more summarized version of the long description. It will be used when users execute an “about” command. Given the space constraints of some channels(eg. Twitter, SMS, etc..) a short description would be more appropriate.
Longer Description
This is the description that will be shown in our repository.
External URI
The URI to your application, eg. http://www.xyz.com/simpledemo.app
Website
URL to your application site, if any. Not for system calls but only to be shown at application page.
Icon
An icon (if any) for your application.

Commands Manager

Commands Manager

Here you will need to register all the official commands that you want your user to be able to execute from the various channels.

For example, in the simpledemo file we have, you will notice that we have 3 commands we want to make available — “hello”, “echo” and “reverse”

To register these commands, you can click on “New Command”.

Name
this is the command name ( Eg. “Hello”)
Description
A description of what the command does ( E.g. “This displays ‘Hello World!’ to the user”)
Excerpt
a more concise version of the description. (E.g. “Returns ‘Hello world’ ”)

Again, the excerpt will only be used for when users make a ‘help’ command from external channels. The full description will be used for when others see your application page.

Once you’re done with registering all your commands, head back to the Commands Manager page.

Now when you view each command option, you’ll see a new box called “Status”. That command only goes live after you’ve set it to “Active”. This enables you to register all your commands without worrying about whether they’ve been completed on the coding end — Just enable it when you’re ready for your users to use it!

For commands that can have sessions, don’t forget to check the “Session-Supported“ box

Now all you need to do is test it…

Testing Your Application

Ok, this is so easy, we really don’t need an entire section for this.

Just type in the command for your application in either the Widgeous Device or any of the supported channels and see if you get the expected out put.

For example, try typing “_simpledemo reverse Reverse this String!” in the Widgeous Device.

Going Live

Well, if you’ve gotten this far, and feel that your application is ready for prime time. Simply edit your application and updates its status to Live. Congratulations for your first live application!

Take it up a notch! Submit for Review

After a while, that “_” really looks ugly doesn’t it? Well, we’ve come up with a process to upgrade the best applications in the Widgeous Ecosystem to the next level by removing the underscore! But it’s going to be a manual process because we want to reserve for the apps that are most used by the Widgeous users.

If you’d like to submit yours for review just click on “Submit for Review” on your application page.

Widgeous Device

minimize What is Widgeous Device?