Canditv API Documentation

Click here to view the API Reference

Getting Started Tutorial

This tutorial outlines the simplest route to getting your application Canditv enabled. It assumes familiarity with Flash application development, specifically with ActionScript 3. It also assumes that you have the latest version of the Canditv SDK library available. Integration with the Canditv API basically boils down to 3 steps:

  1. Create and configure an instance of the core Canditv API class, SessionManager
  2. Wire up event listeners for at least application connection, application disconnection, user connection, user disconnection and user keypress events
  3. Connect to the Canditv servers

Before beginning, ensure that you have an application created that is linking to the Canditv API library, CanditvAPI.swc.

You will also need to ensure you have registered for a valid API key before you can use the Canditv API. If have not already registered you can do so here

Step 1 – Creating and configuring a SessionManager

The SessionManager is the key class within the Canditv API. It manages the underlying connection to the Canditv servers, and provides an interface exposing communication with a connected user. You should declare a single instance of a SessionManager and initialise it as early in the application lifecycle start-up process as possible. The following function shows the minimal implementation for creating a SessionManager, wiring up event handlers and connecting to the Canditv servers:

private function bootStrapCandi():void
{
    _session  = new SessionManager("your API key","your password","0.0.0");
    
    _session.addEventListener(	ApplicationConnectionEvent.APPLICATION_CONNECTED, onApplicationConnection);

    _session.addEventListener(	ApplicationConnectionEvent.CONNECTION_ERROR, onApplicationConnectionError);

    _session.addEventListener(	ApplicationDisconnectionEvent.APPLICATION_DISCONNECTED, onApplicationDisconnected);	

    _session.addEventListener(	SubscriberConnectionEvent.SUBSCRIBER_CONNECTED, onSubscriberConnected);	

    _session.addEventListener(	SubscriberDisconnectionEvent.SUBSCRIBER_DISCONNECTED, onSubscriberDisconnected);

    _session.addEventListener(	SubscriberKeyPressEvent.SUBSCRIBER_KEY_PRESS, onSubscriberKeyPress);
		
    _session.connect();
}

The SessionManager constructor has the following signature:

public function SessionManager( apiKey : String, password : String, applicationVersion : String )

The parameters are defined as follows:

Parameter Description Value
apiKey Your API key Will be provided by DDL
password The password associated with your API key Will be provided by DDL
applicationVersion The version of your application 10 character string, to be defined as you see fit

Step 2 – Wiring Event handlers

Only a handful of events are required for a basic application. This section refers to the events wired up in the bootStrapCandi function referenced in the previous section. The required events are:

Event Description
ApplicationConnectionEvent.APPLICATION_CONNECTED Fired when the connect() method has successfully connected to the Canditv servers. The event raised contains two properties that contain the connection details. ddi (direct dial-in) contains the phone number assigned to the application. pin contains the pin number that a subscriber needs to enter to connect after they dial the ddi.
ApplicationConnectionEvent.CONNECTION_ERROR Fired if an error occurs whilst attempting to connect to the Canditv servers. The message property contains a description of the error encountered. If this event is raised during the very first connection attempt an application makes, you must call the connect method again to attempt reconnection.
ApplicationDisconnectionEvent.APPLICATION_DISCONNECTED Fired when connection to the Canditv servers is lost. This will either occur in the case of a network dropout or after an explicit request to disconnect has been made by calling the SessionManager’s disconnect method. Note that after this event occurs due to a network droput, the SessionManager will be continually attempting to reconnect to the servers (you will see an ApplicationConnectionEvent.APPLICATION_CONNECTED when connection is re-established and possibly ApplicationConnectionEvent.CONNECTION_ERROR events raised whilst the network is down). Best practice when receiving this event unexpectedly is to put the application into a state where the phone number is no longer displayed (as it is not possible for a user to connect via phone at this point) until you receive an ApplicationConnectionEvent.APPLICATION_CONNECTED when connection is re-established.
SubscriberConnectionEvent.SUBSCRIBER_CONNECTED Fired when a user has dialled the application’s phone number and successfully connected to the application. It signals the start of a user session with your application. Contains a subscriber property that exposes details of the user connecting (phone number, etc).
SubscriberDisconnectionEvent.SUBSCRIBER_DISCONNECTED Fired when a user hangs up or loses connection from the application. Contains a subscriber property that contains the details of the outbound subscriber.
SubscriberKeyPressEvent.SUBSCRIBER_KEY_PRESS Fired when a connected user presses a key on their phone. The event contains a subscriber property containing details of the subscriber that pressed the key and a key property that contains the key pressed.

Optionally, you can also register for the following audio playback events, if your application intends to play audio to any connected subscribers via their handsets.

Event Description
SubscriberAudioPlaybackEvent.PLAYBACK_STARTED Fired when confirmation has been received that a request to play audio to a subscriber via the SessionManager’s playAudioToSubscriber method has been received.
SubscriberAudioPlaybackEvent.PLAYBACK_STOPPED Fired when confirmation has been received that an audio playback has completed. Contains properties to indicate the reason for the end of playback and optionally the keys pressed by the subscriber subsequently (if requested via the numKeys parameter on the playAudioToSubscriber method). See the API documentation for further details.

Step 3 – Connecting

Once the SessionManager is configured and event handlers are wired, all that remains is to attempt to connect. This is as simple as calling the connect() method on your SessionManager instance. Once connection either succeeds or fails, you will receive an ApplicationConnectionEvent.APPLICATION_CONNECTED event containing the ddi and pin number assigned to your application. These should be displayed in your application’s UI so that users know what number to dial and what pin to enter to connect to your application.