The Datafree Switch product encompasses a suite of tools that help developers modify existing Apps to run datafree.
To convert an App to datafree with the Datafree Switch product, the developer simply needs to modify the URLs used within the client App to send all data requests via the Datafree Gateway. One key benefit to the Datafree SWITCH Lite approach is speed of development and, in many use cases, the required coding changes in an App can be completed and the App implemented within an hour.
With both approaches the goal is the same - to modify calls to backend services such that they are routed through the Datafree Gateway - that gateway will forward all requests it receives to the appropriate Publisher’s backend server. The Datafree Gateway utilises a set of special IP addresses that have been registered with Mobile Network Operators as a reverse billed service.
In this documentation we outline how Datafree Switch can be used to convert an App to datafree.
For a mobile App to be datafree all the data traffic (requests from the App running on the user’s mobile device plus responses and data sent to that device from the backend services that support the App) must be routed through the Datafree Gateway which has been registered with Mobile Network Operators (MNOs) as a data reverse-billed service. The MNOs use the fact that the Datafree Gateway has been registered as reverse-billed to determine that any user of the Datafree Gateway should not be billed directly for data usage and skips the check whether that user has any data credit.
Datafree Switch implementation
With the Datafree Switch implementation you, as developer, register special ‘free domain names’ within the Datafree Portal that point to the Datafree Gateway and are internally mapped to the domain names of your backend services. The Datafree Gateway receiving the data then uses your registered domain names to identify the traffic and uses the domain mapping you create to determine where it should be forwarded to, sending it to your backend servers or to any third party services you use.
It is necessary to pre-register all the domain names normally used within the client App with Datafree and for each ‘paid domain’ registered, to establish a mapping to a unique ‘free domain name’. This registration and mapping is defined in the Datafree Portal http://pub.bi.nu./
For example you may be allocated the free domain name ‘201.datafree.co’ and then associate it to your backend servers at ‘mycompany.com’. The Datafree Gateway will accept traffic for http://201.datafree.co/ and forward the request header and content to http://mycompany.com/
Paths and parameters in the URL are preserved so http://201.datafree.co/somepath?q=something will be forwarded to http://mycompany.com/somepath?q=something. Multiple domain mappings may be added to access resources from multiple backend servers by prepending text to the free domain e.g. http://images-201.datafree.co/ may be mapped to http://mycdn.com/
- Establish an account in the Datafree Portal.
- Register an Application of type Datafree Switch.
- During registration select ‘Switch Lite - URL rewrite’.
- Once registered, enter the Publisher Designer for the registered App and click ‘Launch Switch Lite Workbench’ button.
- The Workbench provides the means of specifying the domain mappings for your application. Just add entries for the backend services the App uses and for each, an appropriate, unique ‘free’ domain name (source) will be generated. Note : You will need to know all the domains that your App currently uses, as each will be required to be mapped to a datafree domain of the type xxxx-nnn.datafree.co during this step of the process
- The format of the ‘datafree domains’ can only be a single level subdomain of ‘datafree.co’ e.g ‘app-201.datafree.co’ or ‘image-201.datafree.co’. The base free domain will be allocated to you and cannot be changed (201 in these examples) and you are free to prefix that with any alphanumeric string including hyphens but dots are not allowed to maintain the requirement that the ‘datafree domain’ be a single level subdomain of datafree.co.
- The format of the ‘paid domains’ must be the domain only without a protocol and without a path. Additionally a part may be appended if required e.g. mysite.com:8080
- Check ‘HTTPS Only’ if you wish the call to the paid domain to be https.
- Leave ‘Redirect’ unset, it is only used in special cases as the call is redirected to the paid site and therefore will not be datafree.
The following screen shots of the Datafree Portal show the screens referred to above for creation of the necessary datafree Domains.
a) Create a new Switch Lite application using the ‘Getting Started’ wizard
b) In the Publisher Designer screen for the newly created App, accessed from the Datafree Publication List menu item, click the Launch Switch Lite Workbench button
c) On the workbench window add each domain mapping. These entries provide the links from the Datafree Gateway to your company’s domain. Note that entries may be inserted into the Open Zone or the Restricted Zone. The Open Zone has no validation but the Restricted Zone enables validation of the paths of calls made to the Restricted domains. The may be used to provide access control to ensure only allowed resources may be accessed.
d) Push the Config to the Gateway using the green button on the top right of the screen.
For a Development Application you can Push the configuration to the sandbox gateway immediately and start testing although the actual “free” domain is set to the Datafree sandbox environment and contains the subdomain ‘sbox’ which is not Reverse Billed but performs in the same way as production.
For a Production Application, the configuration is pushed to the Datafee Gateway periodically so allow 10-20 minutes for your changes to take effect.
Defining Security Rules
It is important that datafree traffic is controlled to ensure that you do not incur additional costs for unintended traffic. The Datafree Portal delivers a number of features to help you address this.
- The definition of the datafree domain mappings to your target Domains, act as a ‘whitelist’ of domains that are permitted to pass through the Datafree Gateway and resultant data usage is charged to your account. For any domains used that you have not mapped within the Datafree Portal as defined above, the Datafree Gateway blocks the request
- It is also possible to restrict traffic to your App based upon file size and content type, again through the Security Rules screens in the Datafree Portal.
- The Datafree Portal also supports the specification of content size and total daily data limits.
Processing of the request
Once your App has been converted to use the datafree domains the following flow occurs :
- All initial requests from the App are sent via the Datafree Gateway (by the nature of using the datafree Domains in your App).
- The Datafree Gateway uses the Domain mappings that you have set up in the Publisher Portal to determine the final destination address and forwards the request to your webserver/service.
- The response from your webserver/service is sent back to the Datafree Gateway and it then passes that back to the calling App - all responses are compressed by the Datafree Gateway where possible to further reduce the datafree data usage. It should be noted that data sent from your webserver/service as ‘chunked’ data may be aggregated during this process.
- All the request headers are passed ‘as is’, with the exception of the following : (a) Cookies. Cookies are converted from the domain of the webserver to rp.bi.nu. (b) Cache Control is modified so all content sent to the browser is ‘private’ i.e cannot be cached in public caches. This is required to stop the Mobile Network Operators from caching content in their own proxy caches as these make management of reverse-billed content problematic.
- The Datafree Platform supports 2 step certification where one certificate is used for Client-to-Datafree Gateway and a second certificate is used for Datafree Gateway-to-Backend Server. i.e. all traffic is unencrypted and re-encrypted as it passes through the Datafree Gateway. Requests can be http or https requests on either leg. Full end-to-end encryption is not supported with the Datafree Switch product.
The Datafree Portal provides reports to help you manage your Datafree Switch product App traffic. There are two levels of reporting - the standard reports provide details of data usage and data can be viewed in both graph and raw data format. You can also request premium access to our Analytics platform - this gives additional data breakdowns and analytical tools allowing you to interrogate details of the App usage and engagement and consequent data usage - if you are interested in seeing the additional reporting and analysis features of our Analytics platform please contact us.