InstantUssd

InstantUssd is a USSD development library meant to provide you with a set of tools to easily and quickly build your own USSD applications.

Goals

• Speed up USSD development
• Ease maintenance of USSD code

Features

• Minimal coding (Provide USSD menus as config)
• Automatic screen to screen navigation
• Out of the box validation of user inputs
• Ready solutions for complex USSD flows involving going back and forth, optional screens, looping set of screens, jumping from screen to screen and resuming timed-out USSD sessions

Installation

You will need PHP 5.6+ to install this package.

You must then modify your composer.json file and run composer update to include the latest version of the package in your project.

"require": {
    "bitmarshals/instant-ussd": "0.1.*"
}

Or you can run the composer require command from your terminal.

composer require bitmarshals/instant-ussd

Once the package is installed the next step is dependant on which framework you're using.

Usage

Initialization

Instantiate Bitmarshals\InstantUssd\InstantUssd passing in instant_ussd config and your controller instance.

// Within your Controller
use Bitmarshals\InstantUssd\InstantUssd;
use Bitmarshals\InstantUssd\Response;
use InstantUssd\UssdValidator;

$instantUssdConfig = $config['instant_ussd'];
$instantUssd       = new InstantUssd($instantUssdConfig, $this);

Retrieve an instance of Bitmarshals\InstantUssd\UssdService from InstantUssd. This service provides utilities for parsing, packaging and handling incoming USSD data.

$ussdParams  = $_POST;
$ussdText    = $ussdParams['text'];

// package incoming data in a format instant-ussd understands
$ussdService = $instantUssd->getUssdService($ussdText);
$ussdData    = $ussdService->packageUssdData($ussdParams);

Navigation Checks

Before proceeding further we need to run a few test to check if we should exit early, show home page (very first screen in a USSD flow) or navigate to the previous screen.

Exit Check

// Should we EXIT early?
$isExitRequest = $ussdService->isExitRequest();
if ($isExitRequest === true) {
    return $instantUssd->exitUssd([])
                    ->send();
}

Home Page Check

// Should we SHOW HOME Page?
$isFirstRequest       = $ussdService->isFirstRequest();
$userRequestsHomePage = $ussdService->isExplicitHomepageRequest();
if ($isFirstRequest || $userRequestsHomePage) {
    // set your home page
    $yourHomePage = "home_instant_ussd";
    return $instantUssd->showHomePage($ussdData, $yourHomePage)
                    ->send();
}

Go Back Check

// Should we GO BACK?
$isGoBackRequest = $ussdService->isGoBackRequest();
if ($isGoBackRequest === true) {
    $resultGoBak = $instantUssd->goBack($ussdData);
    if ($resultGoBak instanceof Response) {
        return $resultGoBak->send();
    }
    // fallback to home page if previous menu missing
    return $instantUssd->showHomePage($ussdData, 'home_*')
                    ->send();
}

Process Latest User Response

With the navigation checks complete, we should now handle the most recent user response.

Retrieve Last Served Menu and Its Config

InstantUssd keeps a history of the screens we've visited during the current session. Let's retrieve the menu we sent to our user and its config settings.

// get last served menu_id from database
$lastServedMenuId = $instantUssd->retrieveLastServedMenuId($ussdData);
// check we got last_served_menu
if (empty($lastServedMenuId)) {
    // fallback to home page
    return $instantUssd->showHomePage($ussdData, 'home_*')
                    ->send();
}
// Get $lastServedMenuConfig. The config will used in validation trigger below
// Set $ussdData['menu_id'] to know the specific config to retreive
$ussdData['menu_id']  = $lastServedMenuId;
$lastServedMenuConfig = $instantUssd->retrieveMenuConfig($ussdData);
// check we have $lastServedMenuConfig
if (empty($lastServedMenuConfig)) {
    // fallback to home page
    return $instantUssd->showHomePage($ussdData, 'home_*')
                    ->send();
}

Validate Latest Response

// VALIDATE incoming data
$validator = new UssdValidator($lastServedMenuId, $lastServedMenuConfig);
$isValid   = $validator->isValidResponse($ussdData);
if (!$isValid) {
    // handle invalid data
    $nextScreenId = $lastServedMenuId;
    // essentially we're re-rendering the menu with error message
    return $instantUssd->showNextScreen($ussdData, $nextScreenId)
                    ->send();
}

Capture Validated Data

// send valid data FOR PROCESSING. Save to db, etc
// this step should give us a pointer to the next screen
$nextScreenId = $instantUssd->processIncomingData(
        $lastServedMenuId, $ussdData);
if (empty($nextScreenId)) {
    // we couldn't find the next screen
    return $instantUssd->showError($ussdData, "Error. "
                            . "Next screen could not be found.")
                    ->send();
}

Show Next Screen

// we have the next screen; SHOW NEXT SCREEN
return $instantUssd->showNextScreen($ussdData, $nextScreenId)
                ->send();

Sample Application

Check out InstantUssd App.

License

BSD 3-Clause License

Documentation

Please refer to our extensive Wiki documentation for more information.