This is a natural successor to our UssdFramework.
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.
- Automated session management.
- Fully asynchronous.
- Pluggable session store.
RedisStore
included. - ASP.NET MVC / Web Api -ish controllers.
- Dynamic routing.
DataBag
helper in controllers for caching data across requests.- Create forms to collect user input.
- Logging (optional).
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.
The easiest way to install Hubtel.UssdFramework is via NuGet.
PM> Install-Package Smsgh.UssdFramework
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>>
.
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.
It is often convenient to log USSD sessions. Smsgh.UssdFramework supports logging to MongoDB.
Visit mongodb.org/downloads to install MongoDB.
Install Smsgh.UssdFramework.Logging
from NuGet.
PM> Install-Package Smsgh.UssdFramework.Logging
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.
MIT