/ussd-framework

A .NET framework to ease building USSD clients on the SMSGH platform.

Primary LanguageHTML

NOTE: This project has been deprecated in favor of Smsgh.UssdFramework, which is a better alternative.

USSD Framework (deprecated)

A .NET framework to ease building USSD clients on the SMSGH USSD platform.

Features

  • Automated USSD session management.
  • Automated USSD screen navigation. All sub-menus can go back to a previous screen when a user input's 0
  • Automagically resume timed out USSD sessions.
  • Automagically collect user input for specific actions.
  • Encrypt inputs.
  • Fully asynchronous.

Dependencies

  • Redis: This is used to keep session state. It is self-managed by the framework.

Installation

Install from NuGet via Package Manager Console.

PM> Install-Package UssdFramework

Demo

A demo project is included in the source.

This project provides a quick look into how an ASP.NET Web API application can implement the USSD Framework.

The project is configured to run on a local version of IIS at http://localhost/UssdFrameworkDemo.

You can use ussd-mocker to interact with the demo app by using http://127.0.0.1/UssdFrameworkDemo as USSD Client URL.

Basic Concepts

To make the most of the USSD Framework there are a few basic concepts that one must be familiar with.

USSD Screen Types

A USSD app displays various screens to a user. These screens are grouped into 3 main categories:

  • Menu: A menu view where a user enters a number/input to navigate to another screen.
  • Notice: A view that displays some information to a user and ends the session.
  • Input: A view or series of views used to collect user input.

USSD Screen Addresses

For the USSD Framework to know which screen to work with at a particular instance we assign addresses to each screen. The addresses use dot-notation.

For instance, with the Demo app, the start screen has address 1 and is a Menu. Note: Mostly the start screen will be of Menu type.

The menu has 3 options which lead to various screens:

  1. Just greet me: Notice
  2. Greet me with my name: Input
  3. Another menu: Menu

So chosing 1 will take us to another screen with an address of 1.1 which is of type Notice.

Screen flow diagram:

Documentation

  • API: Open UssdFramework.ApiDocs\Help\index.html in a browser to view API documentation. Documentation is generated using Sandcastle.