Hubtel USSD Framework
This is a natural successor to our UssdFramework.
Motivation
The previous UssdFramework was a nice foundation, but it fell short in a few areas.
- Explicit routing.
- Integrated session store.
- Step based flow.
- Unnecessary abstractions that limit flexiblity.
Hubtel.UssdFramework addresses these and a lot more by focusing on simplicity.
Hubtel.UssdFramework allows you to easily build dynamic USSD applications on our USSD platform.
Key Features
- Automated session management.
- Fully asynchronous.
- Pluggable session store.
RedisStoreincluded. - ASP.NET MVC / Web Api -ish controllers.
- Dynamic routing.
DataBaghelper in controllers for caching data across requests.- Create forms to collect user input.
- Logging (optional).
Quick Start
Dependencies
Hubtel.UssdFramework requires a session store. Redis store is included.
On Windows, Redis can be installed using github.com/MSOpenTech/redis.
Don't want to use the bundled RedisStore? Implement IStore using your store backend. Better still, submit a pull request.
Installation
The easiest way to install Hubtel.UssdFramework is via NuGet.
PM> Install-Package Smsgh.UssdFramework
Setup
To process USSD requests, make a static call to Ussd.Process.
Here is a sample setup in an ASP.NET Web Api action.
using System.Threading.Tasks;
using System.Web.Http;
using Smsgh.UssdFramework.Stores;
namespace Smsgh.UssdFramework.Demo.Controllers
{
public class DefaultController : ApiController
{
[HttpPost]
public async Task<IHttpActionResult> Index(UssdRequest request)
{
return Ok(await Ussd.Process(new RedisStore(), request, "Main", "Start"));
}
}
}This tells the framework to route all initial requests to MainController's Start action, which is a method with signature Func<Task<UssdResponse>>.
Controller actions
Next we create our MainController which inherits UssdController.
using System;
using System.Threading.Tasks;
namespace Smsgh.UssdFramework.Demo.UssdControllers
{
public class MainController : UssdController
{
public async Task<UssdResponse> Start()
{
var menu = UssdMenu.New("Welcome", Environment.NewLine + "by SMSGH")
.AddItem("Greet me", "GreetingForm")
.AddItem("What's the time?", "Time")
.AddZeroItem("Exit", "Exit");
return await RenderMenu(menu);
}
public async Task<UssdResponse> GreetingForm()
{
var form = UssdForm.New("Greet Me!", "Greeting")
.AddInput(UssdInput.New("Name"))
.AddInput(UssdInput.New("Sex")
.Option("M", "Male")
.Option("F", "Female"));
return await RenderForm(form);
}
public async Task<UssdResponse> Greeting()
{
var hour = DateTime.UtcNow.Hour;
var greeting = string.Empty;
if (hour < 12)
{
greeting = "Good morning";
}
if (hour >= 12)
{
greeting = "Good afternoon";
}
if (hour >= 18)
{
greeting = "Good night";
}
var name = FormData["Name"];
var prefix = FormData["Sex"] == "M" ? "Master" : "Madam";
return Render(string.Format("{0}, {1} {2}!", greeting, prefix, name));
}
public async Task<UssdResponse> Time()
{
return await Task.FromResult(Render(string.Format("{0:t}",
DateTime.UtcNow)));
}
public async Task<UssdResponse> Exit()
{
return await Task.FromResult(Render("Bye bye!"));
}
}
}And that's it!
See Smsgh.UssdFramework.Demo folder in source for full sample source code.
You can simulate USSD sessions using USSD Mocker.
Logging
It is often convenient to log USSD sessions. Smsgh.UssdFramework supports logging to MongoDB.
Dependencies
Visit mongodb.org/downloads to install MongoDB.
Installation
Install Smsgh.UssdFramework.Logging from NuGet.
PM> Install-Package Smsgh.UssdFramework.Logging
Setup
To enable logging pass an instance of MongoDbLoggingStore when calling Ussd.Process.
using System.Threading.Tasks;
using System.Web.Http;
using Smsgh.UssdFramework.Logging;
using Smsgh.UssdFramework.Stores;
namespace Smsgh.UssdFramework.Demo.Controllers
{
public class DefaultController : ApiController
{
[HttpPost]
public async Task<IHttpActionResult> Index(UssdRequest request)
{
return Ok(await Ussd.Process(new RedisStore(), request, "Main", "Start", null,
new MongoDbLoggingStore("mongodb://localhost", "demoussd")));
}
}
}That's it!
You now have detailed session logs in your MongoDB database. You can use a tool like UMongo to view logs.
License
MIT