Lesson 15: USSD menu explanation and implementation

Recap

In the previous lesson, lesson 14, we suggested a menu that we will implement.

What we note is that, if the user takes route 1, he can select 1 in step 1, again 1 in step 5 and a 1 in step 7. The responses to this replies are apparently different and should be different.

What this means is that, one should track what the user replies with and at what point that reply is made. 
What  the user replies with determines what the user gets, whether he goes to the next, or back or he gets an ‘Invalid reply’.

Note that initially the user sends a request and not ‘anything’, then replies follows after. USSD is session oriented and if the user delays, session expires
Note that a USSD message must be the size of 182 bytes. So keep this in mind
  

Serious stuff now  

Having installed a server in your favorite operating system, and your editor ready, for windows, create a folder named ‘ussdapp’ add a php file in it by name ‘ucuresults.php’. If you are using a different operating system, you probably know what you are supposed to do!

Lets pretend that we placed ‘http://localhost/ussdapp/ucuresults.php‘ as our callback URL in a gateway and it sends this our server

http://localhost/ussdapp/ucuresults.php?serviceCode=*123%23&sessionId=1234DD34&MSISDN=0726172579&text=1

You note that the gateway has added the USSD parameters (we are faking it rememer)
So we receive the value for parameters as shown below.

In serviceCode value is *123#, # is urlencoded as %23. Note that the value for text, 1, is just sample input from a user.

<?php

    $phonenumber = $_GET['MSISDN'];
$sessionID = $_GET['sessionId'];
$servicecode = $_GET['serviceCode'];
$ussdString = $_GET['text'];
?>

 

 The  $_GET[] may be changed to $_POST[], depending on how the gateway sends parameters to the hosting server

    

//create data fields
$regNo="";
$fName="";
$lName="";
$gender="";
$genderV="";
$pass="";
$acceptDeny="";

$username="";
$password="";
$year="";
$semester="";

Then,

start from level 0, when the user has not entered anything

$level =0;
//array_shift($ussdString_explode);

If the user response is not empty we will show the initial, otherwise, we replace # with * so that it will be easier to retrieve response values, as we did in earlier lessons, that the explode() returns an array containing response values. The count function tells us the level we are at, i.e. the number of times the user has responded.
 

if($ussdString != ""){
$ussdString=  str_replace("#", "*", $ussdString);
$ussdString_explode = explode("*", $ussdString);
$level = count($ussdString_explode);
}
if ($level==0){
displaymenu();
}
function displaymenu(){
$ussd_text="CON Welcome to UCURESULTS. Please reply with; <br/>1. Register<br/>2. Login<br/>";
ussd_proceed($ussd_text);
}
function ussd_proceed ($ussd_text){
echo $ussd_text;
//exit(0);
}


 
The displaymenu() gives us what the user initially sees by dialing the USSD code. Because we will be printing or sending text to the user, we write a function ussd_proceed(), which takes our menu as a parameter and prints it for us.

If the user has replied with some replies, then $level will be greater than 0, in fact for the rest of the replies. As shown below, the user reply at index 0 in the returned array determines what route the user wishes to take. We, therefore, pass the value at index zero, so as to determine the route by a switch case control structure. The possible values are 1 or 2. We use functions to handle the routes

   

if ($level>0){
switch ($ussdString_explode[0])
{
case 1:
register($ussdString_explode,$phonenumber);
break;
case 2:
login($ussdString_explode,$phonenumber);
break;
}
}


From above, we have called functions that do not exist. Lets create it
 register function

function register($details,$phone){

if (count($details)==1){
$ussd_text="CON <br/> Enter your registration number (Username)";
ussd_proceed($ussd_text);
}
else if (count($details)==2){
$ussd_text="CON <br/> Enter your first name";
ussd_proceed($ussd_text);
}
else if(count($details) == 3){
$ussd_text = "CON <br/> Enter your last name";
ussd_proceed($ussd_text);
}
else if(count($details) == 4){

$ussd_text = "CON <br/> Select gender  <br/>1. To select male <br/> 2. To select female <br/>";
ussd_proceed($ussd_text);
}else if(count($details) == 5){

$ussd_text = "CON <br/> set your password";
ussd_proceed($ussd_text);
}else if(count($details) == 6){
$ussd_text = "CON <br/>1. Accept registration <br/> 2. Cancel <br/>";
ussd_proceed($ussd_text);
}else if(count($details) == 7){
$regNo=$details[1];
$fName=$details[2];
$lName=$details[3];
$genderV=$details[4];
$pass=$details[5];
$acceptDeny=$details[6];

if($genderV=="1"){
$gender="Male";
}else if($genderV=="2"){
$gender="Female";
}
if($acceptDeny=="1"){
//=================Do your business logic here===========================
//Remember to put "END" at the start of each echo statement that comes here
echo "END <br> Details that will be pushed to the database. <br>Registration number: " . $regNo . "<br>" .
"Name: " . $fName. " " . $lName . "<br>" .
"Gender: " . $gender . "<br>" .
"Password (Encrypted): " . md5($pass) . "<br>";


}else{//Choice is cancel
$ussd_text = "END Your session is over";
ussd_proceed($ussd_text);
}


}
}

 
login function

function login($details,$phone){
if (count($details)==1){
$ussd_text="CON <br/> Enter your Username (registration number)";
ussd_proceed($ussd_text);
}
else if (count($details)==2){
$ussd_text="CON <br/> Enter your password";
ussd_proceed($ussd_text);
}
else if(count($details) == 3){
$ussd_text = "CON <br/> Select your year of study <br/> 1. For year 1 <br/> 2. For year 2 <br/> 3. For year 3";
ussd_proceed($ussd_text);
}
else if(count($details) == 4){

$ussd_text = "CON <br/> Select semister  <br/>1. For semister 1 <br/> 2. For semester 2 <br/>";
ussd_proceed($ussd_text);

}else if(count($details) == 5){
$username=$details[1];
$password=$details[2];
$year=$details[3];
$semester=$details[4];
echo "END We are fetching your exam results using this information <br/>
Username: " . $username . "<br/>" .
"Password (Encrypted): " . md5($password) . "<br/>" .
"Year: " . $year. "<br/>" .
"Semester: " . $semester;
}
}

 
Now a wrap up

script ucuresults.php  

<?php

//for africastalking
$phonenumber = $_GET['MSISDN'];
$sessionID = $_GET['sessionId'];
$servicecode = $_GET['serviceCode'];
$ussdString = $_GET['text'];

//create data fields
$regNo="";
$fName="";
$lName="";
$gender="";
$genderV="";
$pass="";
$acceptDeny="";

$username="";
$password="";
$year="";
$semester="";

//N/B: on going live we will change the GET[] method to POST[] (that is how africastalking do their stuff)
$level =0;

if($ussdString != ""){
$ussdString=  str_replace("#", "*", $ussdString);
$ussdString_explode = explode("*", $ussdString);
$level = count($ussdString_explode);
}
if ($level==0){
displaymenu();
}
function displaymenu(){
$ussd_text="CON Welcome to UCURESULTS. Please reply with; <br/>1. Register<br/>2. Login<br/>";
ussd_proceed($ussd_text);
}
function ussd_proceed ($ussd_text){
echo $ussd_text;
//exit(0);
}
if ($level>0){
switch ($ussdString_explode[0])
{
case 1:
register($ussdString_explode,$phonenumber);
break;
case 2:
login($ussdString_explode,$phonenumber);
break;
}
}
function register($details,$phone){

if (count($details)==1){
$ussd_text="CON <br/> Enter your registration number (Username)";
ussd_proceed($ussd_text);
}
else if (count($details)==2){
$ussd_text="CON <br/> Enter your first name";
ussd_proceed($ussd_text);
}
else if(count($details) == 3){
$ussd_text = "CON <br/> Enter your last name";
ussd_proceed($ussd_text);
}
else if(count($details) == 4){

$ussd_text = "CON <br/> Select gender  <br/>1. To select male <br/> 2. To select female <br/>";
ussd_proceed($ussd_text);
}else if(count($details) == 5){

$ussd_text = "CON <br/> set your password";
ussd_proceed($ussd_text);
}else if(count($details) == 6){
$ussd_text = "CON <br/>1. Accept registration <br/> 2. Cancel <br/>";
ussd_proceed($ussd_text);
}else if(count($details) == 7){
$regNo=$details[1];
$fName=$details[2];
$lName=$details[3];
$genderV=$details[4];
$pass=$details[5];
$acceptDeny=$details[6];

if($genderV=="1"){
$gender="Male";
}else if($genderV=="2"){
$gender="Female";
}
if($acceptDeny=="1"){
//=================Do your business logic here===========================
//Remember to put "END" at the start of each echo statement that comes here
echo "END <br> Details that will be pushed to the database. <br>Registration number: " . $regNo . "<br>" .
"Name: " . $fName. " " . $lName . "<br>" .
"Gender: " . $gender . "<br>" .
"Password (Encrypted): " . md5($pass) . "<br>";


}else{//Choice is cancel
$ussd_text = "END Your session is over";
ussd_proceed($ussd_text);
}


}
}

function login($details,$phone){
if (count($details)==1){
$ussd_text="CON <br/> Enter your Username (registration number)";
ussd_proceed($ussd_text);
}
else if (count($details)==2){
$ussd_text="CON <br/> Enter your password";
ussd_proceed($ussd_text);
}
else if(count($details) == 3){
$ussd_text = "CON <br/> Select your year of study <br/> 1. For year 1 <br/> 2. For year 2 <br/> 3. For year 3";
ussd_proceed($ussd_text);
}
else if(count($details) == 4){

$ussd_text = "CON <br/> Select semister  <br/>1. For semister 1 <br/> 2. For semester 2 <br/>";
ussd_proceed($ussd_text);

}else if(count($details) == 5){
$username=$details[1];
$password=$details[2];
$year=$details[3];
$semester=$details[4];
echo "END We are fetching your exam results using this information <br/>
Username: " . $username . "<br/>" .
"Password (Encrypted): " . md5($password) . "<br/>" .
"Year: " . $year. "<br/>" .
"Semester: " . $semester;
}
}
?>

With this code, try running this in your browser: http://localhost/ussdapp/ucuresults.php?serviceCode=*123%23&sessionId=1234DD34&MSISDN=0726172579&text=
In this lesson, we have done a simple USSD code and it has been dense.
In the next lesson, we explain our code into detail and a bit of how we test this application using our browser now that we have real USSD gateway.

Don’t shy away leaving a comment.    

16 Comments
    • Derdus Kenga
    • Derdus Kenga
    • Derdus Kenga
    • Derdus Kenga

Add a Comment

Your email address will not be published. Required fields are marked *