Datafree Max - Getting Started Guide

Datafree Max - Getting Started Guide

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 Optimizer optimizes the content transiting it, content that the Max client requests and are serviced by the publisher’s server. This optimizer 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 biNu 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 customized 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 biNu 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 biNu ‘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 


<app title = "Hello World">
   
<drawer>
       
<menuitem
           
href="helloworld.xml"
           
default="true">
            Homepage
       
</menuitem>
   
</drawer>
</app>


where:

  • <app> - identifies this file as a biNu 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’.


<doc title="Hello World">
<md>Hello World</md>
</doc>


where:

  • <doc> - identifies this as a biNu 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 biNu 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