JavaScript SDK getting started guide
The Internet Clicker JavaScript SDK allows you to programmatically control the clicker and respond to server-sent events via a simple-to-use API. Using this you can build elements of the clicker interface directly into your own site, allowing you to create your own UI around the functionality of Internet Clicker.
Note: Along with the below documentation, you can also access working demos here and here.
Getting started
First, you'll need to include the SDK in your HTML document. You can use the CDN hosted version or download and self-host. Include it in the <head> of your document:
<script type="text/javascript" src="https://sdk.internetclicker.com/ic.min.js"></script>
Below is a simple example of how to connect to the clicker code "event2021" and trigger events to move slides forwards and backward.
<html>
<head>
<script type="text/javascript" src="https://sdk.internetclicker.com/ic.min.js"></script>
</head>
<body>
<div>
<button @onclick="clicker.previous()">Previous</button>
<button @onclick="clicker.next()">Next</button>
</div>
<script>
var clicker = new IC.Connection();
clicker.start('event2021');
</script>
</body>
</html>
We'll now break down this sample code and discuss what's going on here.
As shown above, we instantiate the Internet Clicker connection object by calling:
var clicker = new IC.Connection();
This object can then be used to handle any events and trigger calls to the server. In the below, we attempt to connect to the server with the presenter code "event2021":
clicker.start('event2021');
If you're controlling clicking access via the Control Center on the website, you may also provide a username for the connection like so:
clicker.start('event2021', 'Bob');
If this code is currently connected to the server via one of the desktop applications or application plugins, we'll then be connected to the Internet Clicker server.
From here we can start calling methods, such as moving the slide forwards and backward as shown below:
// Previous slide
clicker.previous();
// Next slide
clicker.next()
In the full sample above, we've attached the function calls to the onclick events of two buttons, but you can also call them directly from your JavaScript.
With this sample, you're up and running and can now move slideshows forwards and back from your own webpage! We'll now dig deeper into handling events from the server and further function calls.
For the purpose of these samples, we'll be logging directly to the console of your browser. You'll be able to see this output in the developer tools for your chosen browser.
Handling connection success and failure
So, how can we tell if the connection to the server has succeeded and how can we provide logic to handle what happens when it succeeds or fails? By using event handlers accessible through the IC.Connection() object.
The sample below shows the event triggered when a connection to the server has been successful:
clicker.on('connectSuccess', function(payload) {
// payload
/*
{
isActive: Boolean
}
*/
if(payload.isActive) {
console.log("User can click")
} else {
console.log("User cannot click")
}
});
Here we can see the general form of event handlers within the SDK. We use the .on() method directly on an instance of IC.Connection();. The parameters for this call are the event name (in this case "connectSuccess") and a function called when the event is received, complete with a parameter for the object returned from the server (here we call it "payload").
The payload for the "connectSuccess" event handler contains a single property "isActive". This property lets us know if the user is able to perform clicking actions at that time, i.e. has clicking been disabled for this user in the control center?
The next event we'll look at is triggered when the connection attempt has reached the server and has not been successful. There are a number of reasons why this can occur and the exact cause is returned in the payload as a property called code. The possible codes are as follows:
- "sdkNotEnabled" - The SDK has not been enabled on the account that is hosting this code
- "codeNotFound" - The code does not exist on any client connected to Internet Clicker
- "codeRequired" - No code was provided during the connection event
- "nameRequired" - This code has presenter access control turned on but no username has been provided
- "connectionError" - This indicates a connectivity issue with the user's internet preventing a connection from being established
A friendly message explaining the code will also be provided so we can easily tell what's going on if something's wrong.
Here's an example of what this event handler looks like:
clicker.on('connectError', function(payload) {
// payload
/*
{
code: String,
message: String
}
*/
console.log(payload.code)
console.log(payload.message)
});
Connection state change
Once connected, it is possible that the user's connection state to the Internet Clicker server may change. An event is triggered when this occurs that tells us within the browser what's happening. The following state changes can occur:
- "reconnecting" - When the connection with the server is lost the SDK will first attempt to reconnect automatically
- "reconnected" - The reconnection attempt was successful and we're up and running again
- "closed" - After a period of reconnection attempts a connection to the server was unable to be established and attempts to reconnect have been stopped.
The payload object contains a single property with one of the values listed above.
Here's an example of how this event handler looks:
clicker.on('connectionStateChanged', function(payload) {
// payload
/*
{
state: String
}
*/
console.log(payload.code)
});
Screenshot taken
When screenshots are enabled on the client application we can hook into an event that'll give us the URL of the new screenshot so we can display it to the user. The payload contains a single property called url - the URL of the screenshot. URLs are valid for 5 minutes and we only store the latest screenshot, which is deleted once the event finishes.
Here's an example of this event handler:
clicker.on('screenshotChange', function(payload) {
// payload
/*
{
url: String
}
*/
console.log(payload.url)
});
Speakers note changed
The PowerPoint plugin can enable speaker notes to be shared with the presenter. When the speaker notes change within the plugin an event is sent to the browser containing the new notes - which can then be displayed within our page. The payload contains a single property called notes - the notes that have been sent over.
Here's an example of this event handler:
clicker.on('speakerNotesChange', function(payload) {
// payload
/*
{
notes: String
}
*/
console.log(payload.notes)
});
User message
Users on the Internet Clicker control center can send messages directly to the presenter. An event with a payload, containing a message property, will then be sent to the presenter's browser - which can then be displayed on our page.
Here's an example of this event handler:
clicker.on('userMessageReceived', function(payload) {
// payload
/*
{
message: String
}
*/
console.log(payload.message)
});
Timer started
The timer started event is triggered either when a new timer is started within the control center or when the presenter has connected and a timer is already in progress.
The payload for this event contains two properties; the number of seconds the timer is currently on (seconds) and whether or not the timer is currently active (isActive). This second property is important to note in situations when the presenter connects while the current timer is paused.
The isCountingUp property lets you know if the timer should start counting up once the count reaches 0. At this point, you'll start receiving negative seconds to use to distinguish that it's now counting up.
Note: Due to network events outside of our control, we can't guarantee this won't be called before connectSuccess.
Here's an example of this event handler:
clicker.on('timerStarted', function(payload) {
// payload
/*
{
seconds: Number,
isActive: Boolean,
isCountingUp: Boolean
}
*/
console.log("Seconds remaining: ", payload.seconds);
if(payload.isActive) {
console.log("Timer is running");
} else {
console.log("Timer is paused");
}
if(payload.isCountUp){
console.log("Timer will count up on finish");
}else{
console.log("Timer will end at zero seconds");
}
});
Timer paused
When the timer is paused in the control center we'll receive an event letting us know the number of seconds it was paused at. The payload contains a single property called seconds.
Here's an example of this event handler:
clicker.on('timerPaused', function(payload) {
// payload
/*
{
seconds: Number
}
*/
console.log("Seconds remaining: ", payload.seconds);
});
Timer stopped
When the timer is stopped (i.e. cannot be restarted in the control center) within the control center we'll receive the timer stopped event so the presenter can be informed. This event has no payload, when it's called we implicitly know the timer has been destroyed.
Here's an example of this event handler:
clicker.on('timerStopped', function() {
console.log("Timer stopped");
});
Client connection state changes
If the client application or plugin changes its own state - such as disconnecting or reconnecting to the Internet Clicker server, we receive an event letting us know this new state. This state is a string that can be one of the following:
- "connected" - The client application has connected once again to the Internet Clicker server
- "closed" - The client application has disconnected from the Internet Clicker server
clicker.on('clientStateChanged', function(payload) {
// payload
/*
{
state: String
}
*/
console.log("Client connection is ", payload.state);
});
User removed
Within the control center, a presenter can be disconnected from the event by the user, stopping any future communication with the Internet Clicker server.
This event has no payload - if this method is triggered we implicitly know the presenter is no longer connected.
Here's an example of this event handler:
clicker.on('userRemoved', function() {
console.log("User has been removed");
});
Disconnecting and clean up
To destroy the Internet Clicker instance, stop any connection to the server, and remove the iframe created to handle the connection we can call a simple destroy method like so:
clicker.destroy();
Calling .start() on the IC.Connection() object again will recreate the iframe and reconnect.
Full sample page
Putting it all together to give us a full page to start with we get:
<html>
<head>
<script type="text/javascript" src="https://sdk.internetclicker.com/ic.min.js"></script>
</head>
<body>
<div>
<button @onclick="clicker.previous()">Previous</button>
<button @onclick="clicker.next()">Next</button>
</div>
<script>
var clicker = new IC.Connection();
clicker.start('event2021');
// When browser connects to IC server successfully
clicker.on('connectSuccess', function(payload) {
// payload
/*
{
isActive: Boolean
}
*/
if(payload.isActive) {
console.log("User can click")
} else {
console.log("User cannot click")
}
});
// When there's an issue connecting to IC server
clicker.on('connectError', function(payload) {
// payload
/*
{
code: String,
message: String
}
*/
console.log(payload.code)
console.log(payload.message)
});
// Browser's connection to the IC server has changed
clicker.on('connectionStateChanged', function(payload) {
// payload
/*
{
state: String
}
*/
console.log(payload.code)
});
// When a new screenshot URL has been sent to browser
clicker.on('screenshotChange', function(payload) {
// payload
/*
{
url: String
}
*/
console.log(payload.url)
});
// When the speaker notes have updated on plugin app
clicker.on('speakerNotesChange', function(payload) {
// payload
/*
{
notes: String
}
*/
console.log(payload.notes)
});
// Control center has sent browser a message
clicker.on('userMessageReceived', function(payload) {
// payload
/*
{
message: String
}
*/
console.log(payload.message)
});
// A timer has started or browser has received existing timer on connection
clicker.on('timerStarted', function(payload) {
// payload
/*
{
seconds: Number,
isActive: Boolean
}
*/
console.log("Seconds remaining: ", payload.seconds);
if(payload.isActive) {
console.log("Timer is running");
} else {
console.log("Timer is paused");
}
});
// The timer has been paused in the control center
clicker.on('timerPaused', function(payload) {
// payload
/*
{
seconds: Number
}
*/
console.log("Seconds remaining: ", payload.seconds);
});
// The timer has been stopped (completely) in control center
clicker.on('timerStopped', function() {
console.log("Timer stopped");
});
// The client app/plugin's state has changed
clicker.on('clientStateChanged', function(payload) {
// payload
/*
{
state: String
}
*/
console.log("Client connection is ", payload.state);
});
// The browser's user has been removed from the event from control center
clicker.on('userRemoved', function() {
console.log("User has been removed");
});
// To destroy the connection/iframe
// clicker.destroy();
</script>
</body>
</html>
Custom Clicker Additions
If you've also got access to the Custom Clicker add-on you can also send keys for 0-9 and a-z. This is achieved using the clicker.sendCustomKey(key) function as shown in the below example. As you can see the word zero is used instead of the numeral - due to how our system works under the hood.
clicker.send('zero');
Here's a list of keys and the arguments needed to trigger them.
Note: the arguments are case-sensitive.
| Key | Argument |
| 0 | zero |
| 1 | one |
| 2 | two |
| 3 | three |
| 4 | four |
| 5 | five |
| 6 | six |
| 7 | seven |
| 8 | eight |
| 9 | nine |
| A | a |
| B | b |
| C | c |
| D | d |
| E | e |
| F | f |
| G | g |
| H | h |
| I | i |
| J | j |
| K | k |
| L | l |
| M | m |
| N | n |
| O | o |
| P | p |
| Q | q |
| R | r |
| S | s |
| T | t |
| U | u |
| V | v |
| W | w |
| X | x |
| Y | y |
| Z | z |
Comments
0 comments
Article is closed for comments.