Articles & Information.

Tutorial 1: Building Your First Mxit Mobi Portal App

Select a topic:

Choose from one of the topics below to browse other articles

Last updated by Rudolph Keown on September 02, 2013 14:59

In this tutorial, we will be building the classic 1 page "Hello Mxit" Mobi Portal app. To keep things simple, we'll use "apptestrm1" as the app name and http://testappmxit.eu01.aws.af.cm/ as the Mobi URL.


Step 1 - Creating the app

For our first app, here is the source code to display “Hello Mxit! Congratulations on building your first Mxit app.” We will be making use of the Mobi portal API Specification information: 

<html>
 <head>
   <meta name="mxit" content="clearscreen,no_prefix,show_progress"></meta>
 </head>
   <body>
     <h1>Hello Mxit!</h1>
      Congratulations on building your first <i>Mxit</i> app.
  </body>
</html>
Save this somewhere. The filename isn’t terribly important as we will be pasting it into an index.php that our cloud provider sends us. 


Step 2 - Set up your server (Appfog) 

Follow the steps below to set up your server - it's quick and easy.  We have chosen to use appfog for this tutorial due to its easy integration with the REST APIs. There are a number of other hosting options like EC2. Feel free to use whichever one you prefer but these instructions are specific to appfog.

  1. Create an account on Appfog: Click on "Sign Up" and complete the "Create an Account" Form and click on "Signup" once done.
  2. Choose an application on which your code is based, we are using PHP so click on the PHP button.
  3. Choose an infrastructure. We will be going with AWS Europe West (Ireland) for this.
  4. Choose a domain. For this tutorial, we chose "testappmxit" (http://testappmxit.eu01.aws.af.cm/). Once you've clicked on "Create App" it sets up your app, so please wait for it to complete. This can take a while. If the menu at the left comes up empty, reload the page until you see it. 


Step 3 - Upload your Appfog app

 In Appfog click on Visit Live Site to see what you current app looks like in a browser:


Figure 1: To view your current app.

This will be the basis for our little Mxit app; we now need to modify this PHP Source code. Click on Update Source Code to proceed in doing this.


Figure 2: On the left side of the screen inside Appfog.


Follow the on screen instructions to modify the source code. Appfog uses a Ruby gem - a small script written in the Ruby language - called 'af' to do its updating. If you don't have Ruby installed, do that first before attempting to install af. Links are provided on appfog's page. The Download Source code button will send you a zip file called yourdomainname.zip. Extract this to a folder of the same name. In our case it sent testappmxt.zip so we make a directory called testappmxt and extract the file in there. Inside the zip is a single file - index.php - which is appfog's placeholder. Delete this line and replace it with the contents of the html you saved in Step 1 . Valid HTML is valid PHP so it will execute correctly. 

Then follow the update instructions. You must be inside the testappmxit directory for it to work correctly. When the update finishes check that your site is now running the new index.php. 


Step 4 - Create your Mxit developer account

In order to have your application run on Mxit you need to create a developer account on: http://dev.mxit.com .If you don't already have a developer account you will need to follow the sign up process and create an account. Once this is completed, you will receive an activation email from Mxit. 
You will not be able to access the dashboard needed to have your app on Mxit until you verify by clicking on the link in the e-mail. 


Step 5 - Set up your app on Mxit

Sign into your developer account and click on "Mobi Portal API". Click on "Create your Mobi-Portal" at the top right of the screen.


Figure 3: Mobi Portal Dashboard, Create your Mobi Portal App. 


In the form, you'll need to provide your Application Name (apptestrm1) and Application Alias (Test Application)  as well as the Mobi Site URL (http://testappmxit.eu01.aws.af.cm/).

The Application Name is a unique identifiable name which users may use to add your app manually on Mxit, and it can be alphanumeric and may contain underscore, hyphen, and full stops.  The Application Name may not continue spaces or any special characters. The Application Alias is used for display purposes and is seen when users add your app in Mxit, and can consists of anything. And the URL is used by Mxit to determine where your app is hosted. If you successfully entered all the information correctly you will see a green tick and can proceed. 


Figure 4: Create your Mobi-Portal Form - Information correctly supplied.


Once you click on the "Save" button your app will be in Beta state immediately but could take up to one hour to be live. 

Congratulations on having your first app on Mxit!

To see what the app looks like on Mxit, using our PC client, Mxit Evo:



Figure 5: Your first Mxit Mobi app inside of Mxit.


It is important to note:  

Mobi Portal apps can be in twostates (beta and published). When you launch your Mobi Portal app for the first time, it is in Beta.

This means users can manually add the app if they have the app name and you as the developer can see its behaviour in Mxit. If at any time you wish to update your app, you simply log into your dashboard and click on the Application Name you wish to edit and make the changes. Please allow at least 1 hour for any update to be pushed through live on the Mxit client.
Now that the groundwork has been done, we can start adding some functionality to our application. 


What's Next?

In Tutorial 2, we’ll be expanding our app to include basic navigation.