Skip to end of metadata
Go to start of metadata

Overview

USSD (Unstructured Supplementary Service Data) is a real-time text interface for GSM enabled handsets.

USSD is limited in capability in comparison to the Ramp native mobile application and HTML 5 channels due to its text only nature.

A separate library is therefore provided for USSD that allows certain integration components to be shared between USSD, Ramp native mobile application and HTML 5 channels.

The library can be downloaded here

USSD library

The Javadocs for the USSD library is available here.

For an USSD application developer the major concepts are:

  • Connector

Performs the transformation of USSD messages to and from the USSD gateway.

  •  View

Equivalent to a single USSD screen.

A view can render itself and receive input from users.

  • MenuItem

Represents a selectable item on a View. Has a "view" property which indicates which View should be navigated to when this item is selected.

MenuItem, BasicView and BasicViewWithSpringMenuItem are the main classes that an USSD application developer will use to construct the USSD channel.

Integrating the USSD library with the Ramp server

In order to integrate the USSD library with the Ramp server the Ramp USSD library must be placed in your integration context folder (e.g. /etc/ramp/integration) along with a context configuration file that configures the USSD channel. 

As with all context configuration files, it should end with -context.xml (e.g. ussd-context.xml). 

An example USSD context configuration is provided below. 

 

Sample USSD context
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans" xmlns:util="http://www.springframework.org/schema/util" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://www.springframework.org/schema/beans 
                        http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
                        http://www.springframework.org/schema/util 
                        http://www.springframework.org/schema/util/spring-util-2.5.xsd">

	<bean id="ussdMapper" class="org.springframework.web.servlet.handler.SimpleUrlHandlerMapping">
		<property name="urlMap">
			<map>
				<entry key="/ussd/*" value-ref="ussdController"></entry>
			</map>
		</property>
		<property name="order" value="1" />
	</bean>

	<bean id="ussdController" class="com.vmt.ramp.ussd.Controller">
		<constructor-arg index="0" ref="ussdConnector"></constructor-arg>
		<constructor-arg index="1" ref="ussdSessionManager"></constructor-arg>
		<constructor-arg index="2" ref="ussdViewResolver"></constructor-arg>
		<constructor-arg index="3" ref="ussdExceptionResolver"></constructor-arg>
		<constructor-arg index="4" ref="requestFilter"></constructor-arg>
	</bean>

	<bean id="ussdSessionManager" class="com.vmt.ramp.ussd.core.SessionManager" init-method="init" destroy-method="destroy" />

	<bean id="ussdViewResolver" class="com.vmt.ramp.ussd.ViewResolverImpl">
		<lookup-method bean="mainView" name="retrieveRootView" />
	</bean>

	<bean id="ussdConnector" class="com.vmt.ramp.ussd.connectors.HttpQueryParameterConnector"></bean>

	<!-- <bean id="ussdConnector" class="com.vmt.ramp.ussd.connectors.TruTeqConnector"></bean> -->

	<bean id="ussdExceptionResolver" class="com.vmt.ramp.ussd.exceptions.BasicExceptionResolver">
		<constructor-arg index="0" ref="mainMenuItem"></constructor-arg>
	</bean>

	<bean id="requestFilter" class="com.vmt.ramp.ussd.AllowAllFilter">
	</bean>

	<!-- <util:list id="allowedIps"> <value>196.30.141.151</value> <value>127.0.0.1</value> </util:list> <bean id="requestFilter" class="com.vmt.ramp.ussd.IPRequestFilter"> <constructor-arg ref="allowedIps"></constructor-arg> 
		</bean> -->

	<bean id="mainView" class="com.vmt.ramp.ussd.views.BasicViewWithSpringMenuItems" scope="prototype" lazy-init="true">
		<property name="menuItemNames">
			<list>
				<value>aboutRampUssdItem</value>
			</list>
		</property>
		<property name="msg" value="Welcome to Ramp USSD. Select option:"></property>
	</bean>

	<bean id="aboutRampUssdView" class="com.vmt.ramp.ussd.views.BasicView" scope="prototype" lazy-init="true">
		<property name="msg" value="USSD is a real-time text interface for GSM enabled handsets. Ramp USSD adds support for USSD to the Ramp platform. "></property>
		<property name="options">
			<list>
				<ref bean="mainMenuItem"></ref>
			</list>
		</property>
	</bean>

	<bean id="mainMenuItem" class="com.vmt.ramp.ussd.core.MenuItem" scope="prototype" lazy-init="true">
		<property name="view" ref="mainView"></property>
		<property name="text" value="Main Menu"></property>
	</bean>

	<bean id="aboutRampUssdItem" class="com.vmt.ramp.ussd.core.MenuItem" scope="prototype" lazy-init="true">
		<property name="view" ref="aboutRampUssdView"></property>
		<property name="text" value="About Ramp USSD"></property>
	</bean>

</beans>

Testing prior to integrating with USSD gateway

The connector that is used in the example ussd-context.xml file is the HttpQueryParameterConnector. This connector is used for testing prior to integrating with a USSD gateway. One uses HTTP query parameters to simulate the values that would be set by the USSD gateway. Here is an example of how to use it:

http://127.0.0.1:8080/ramp/http/ussd/?phase=FIRST&msisdn=27821234567
http://127.0.0.1:8080/ramp/http/ussd/?phase=SESSION&msisdn=27821234567&msg=1

HTTP query parameters

ParameterValue
phaseShould be "FIRST" or "SESSION"
msisdnThe MSISDN (cell phone number)
msgThe message that the user has sent representing the menu item they have selected

Integrating with a USSD gateway

To integrate with a USSD gateway, edit the "ussdConnector" bean in the ussd-context.xml file to be a USSD gateway connector, e.g. the TruTeqConnector which is commented out in the example ussd-context.xml. Check the USSD Javadocs to see if there is already a connector for your chosen USSD gateway provider. If not, you will need to write your own connector to integrate with the gateway.

  • No labels