Skip to main content

Datafree Max - Getting Started Guide

  • Updated

Datafree Max -  Getting Started Guide

 

This guide provides an introduction to developing Android Apps with Datafree Max. It is intended to get you started with your first App. More in-depth information is available in the Datafree Max Developer Reference Guide.

 

Platform Architecture

The Datafree Max Publishing Platform is comprised of 3 major components:

 

  • The Max client App which can be generated from pub.bi.nu. There is no programming of this client required. The App talks to your server where Datafree Max XML pages are hosted. These pages are then displayed and executed by the app.  The Max client runs on Android 4.1 and above.

 

  • The Datafree Max Optimiser optimises the content transiting it, content that the Max client requests and are serviced by the publisher’s server. This optimizser is managed by Datafree and is not configured by the developer.

 

  • The server-side Datafree Application which consists of XML files to define the configuration and layout of the client App and provide content to be rendered in the App. The development of a Max Application involves the programming of a server-side application to serve the XML pages. This is the only component that needs to be developed by a publisher to create a Datafree Application.

 
 

 
 

Developing Datafree Max Applications

The process to develop a new Application starts by registering as a Datafree developer and obtaining your own branded, version of the client App.

 

1. Register as a Datafree Developer

 

Register at the Datafree Portal - pub.bi.nu and once accepted you will receive a password by email. After logging into the developer portal you will be able to register a Datafree Max Application and gain access to additional developer resources to help you with development.

 

2. Register your Max Application

 

On registering a new Application we will supply a customised client App for you as an Android .APK file. The App is branded to your requirements and no further development of the App is required (i.e. you do not need to be an Android developer or have access to Android development tools).

 

To register a new Application, log on to the Datafree Portal and choose ‘Register New Application’. You will need to provide the following information which is ‘burned’ into the Android apk file when it is generated. Note that you can regenerate the App at any time if changes are required.

 

You will need to provide:

 

  • the Application name and version;

  • the Application package name (e.g. com.mycompany.application);

  • an app icon - a 120x120 pixel PNG file;

  • a splash screen image - a 1080x1920 PNG image;

  • a homepage URL;

There are other optional parameters which are fully described in the Datafree Max Developer Reference Guide and not required to complete first app.

 

The homepage URL is the ‘starting point’ for your Application. It must point to a valid Datafree XML configuration file that is publicly available using http. The file describes the layout of your Application and initial content to be rendered when the Application is launched.

 

3. Generate your Datafree Application

 

To generate the .APK client for your Application, log on to the Developer Portal and choose ‘Generate APK file’. You will need to provide a the following information to generate the apk file:

 

  • a Version Name, e.g. dev1.0;

  • a Version Code, e.g. 1.

 

You have the option to generate the file as signed or unsigned. If you choose signed, then it is signed with the Datafree developer certificate otherwise it is unsigned and you will need to sign the apk with your own certificate.

 

For development purposes only, you can choose to generate the signed apk and you will be able to install it on devices for testing. When you are ready to deploy your Application, you must generate an unsigned .apk from the Datafree Portal and then ‘sign it’ using your own key (issued by Google). Signing an .apk is a standard requirement for Android and the Play Store and is managed by Google. For more information on signing an apk: https://developer.android.com/studio/publish/app-signing.html#release-mode 

 

After generating the .APK, you will receive an email with a link to download the apk file, this may take 10-15 minutes to arrive. When you click the link you will be prompted to log on to the developer portal to start the download.

 

4. Install the client App

 

The download link may be used either on the device or on a computer. 

 

To install on your android device, click the link in the email to download the .apk file to your downloads folder. You will then get an option to install it or you can click on the .apk file in the downloads folder to install it. 

 

To install from your computer, click the link in the email and download the .apk file to your computer. Then connect your device and use Android File Transfer to copy it to the downloads folder on your device. Then click on the .apk file in the downloads folder to install it.

 

It is also possible to run the .apk within an Android emulator, there are several available to choose from.  

 

Developing Apps

You will need access to a publicly available (via http) folder to store XML configuration files and other resources that comprise your Datafree Application. The folder must be at the homepage URL defined when generating the client App.

 

1. Develop your first Datafree Max Application

 

When launched, the client App reads the XML file at the homepage URL to configure the environment, including the header, menus, stylesheet and content to display on the page.

 

Let’s start by building a Datafree ‘Hello World’ Application. It consists of 2 XML files, the Application configuration file and the document configuration file.

 

If you are not familiar with XML, you can find out more at https://www.znetlive.com/blog/xml-tutorial-for-beginners

 

Application configuration file 

 

This is the file defined in the homepage URL:

e.g. http://yourhost/yourbinuapplication/app.xml 

 

title = "Hello World"
   
       
            href="helloworld.xml"
            default="true"
            Homepage
       
   

 

where:

  • <></>app - identifies this file as a Datafree App configuration file

  • title - the App title to be displayed 

  • <></>drawer - specifies the items to be shown in the Navigation Drawer of your App. <></>menuitem - defines a menu item - “Homepage” 

  • href - specifies the location of the content to be loaded for the item

  • default - a value of true will load this menu item’s content when the App is loaded.

 

Document configuration file 

 

This is the file referenced by the drawer menu item in the Application configuration file above. It this example is is named ‘helloworld.xml’.

 

title="Hello World"
Hello World
 

where:

  • <></>doc - identifies this as a Datafree document file

  • title - is the document title

  • <></>md - defines a Markdown text block - “Hello World”

 

This example does not have any markdown formatting, however if you are new to Markdown, you can find out more at http://commonmark.org/help/  or explore the Datafree Knowledge Base.

 

This Hello World App may seem trivial but when you see “Hello World” on your device, you have established a fully functional Datafree development environment and can move on to the next section which will show you how to add components and content to your App.

 

If you do not see Hello World then you should check the homepageUrl is correct and that it is publicly available. If you are still having problems the you can use the developer portal to contact our support team for assistance.

 

2. Next Steps

 
You are now ready to move on to the Datafree Developers Reference Guide which will take you through all the components and enable you to build a fully functional Datafree Application. 

 

There is a sample application to help you get started. The code is available on Github at:  https://github.com/binuadmin/biNu-sample-1




 

Related articles