Switch Product Overview

Switch Product Overview


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.

The Approach

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/

First Steps:

  1. Establish an account in the Datafree Portal. 
  2. Register an Application of type Datafree Switch. 
  3. During registration select ‘Switch Lite - URL rewrite’.
  4. Once registered, enter the Publisher Designer for the registered App and click ‘Launch Switch Lite Workbench’ button.
  5. 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
  6. 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.
  7. 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
  8. Check ‘HTTPS Only’ if you wish the call to the paid domain to be https.
  9. 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. 
  1. 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
  2. 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. 
  3. 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 :
  1. All initial requests from the App are sent via the  Datafree Gateway (by the nature of using the datafree Domains in your App).
  2. 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.
  3. 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. 
  4. 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.
  5. 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.

Tracking and Reporting

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. 

Identifying datafree vs ‘paid’ Traffic

With the Datafree Switch product the Datafree Platform depends on algorithms to judge whether the traffic is datafree or not. It is estimated that 80-85% of the datafree traffic will be identified. The reverse-billed data you are charged for is adjusted to allow for this inaccuracy.  If you envisage that a significant proportion of traffic will not be reverse-billing then contact Datafree Support to discuss options. 

Steps to modify an existing App for Switch

This is a recommended set of steps to follow if you are planning to convert an existing App to run on the Datafree Platform: 
  1. Identify all your network activity. To reverse-bill mobile data all the traffic from your App must be directed through the Datafree Gateway (our Gateway use a small number of IP addresses specifically registered with the MNOs for reverse-billing). If data from your App cannot be directed through the Datafree Gateway, it will be billed to the user or, if they have no mobile data, data requests will fail. Therefore, the first task is to identify all the traffic your App uses and determine if you can redirect it through the Datafree Gateway using datafree Domains. The core data for your App is the most obvious and easiest traffic to control.  The less obvious areas you should investigate are: 
    1. The development tools used to build the App. These often generate their own traffic. Pulling in code, libraries, javascript or storing data in a backend. Google’s Firebase, for example, cannot be reverse-billed. 
    2. Third Party SDKs used. These may be for advertising, analytics, tracking, etc.
    3. There are few Apps that don’t include one of these and usually can’t be reverse-billed. 
    4. Third Party Content. Does your App do ‘mashups’ with content pulled from a number of sources. Can you modify the URLs used?
    5. Logins and Verifications. Do you use Facebook, Google or others to identify users. These services will not allow traffic to pass through a Gateway like Switch uses.
    6. Secure Transactions. Do you talk to backend services for special transactions? It may be possible to route this data via a special Datafree Gateway but often the third party provider will have extra security rules that may fail the requests. 
    7. Content Distribution Networks. This optimises your App’s performance by delivering content from servers close to the user but can’t be reverse-billed and will need to be handled in a different way.
    8. Non-HTTP traffic. Standard HTTP traffic can be reverse-billed but traffic using different protocols may need special attention.  
  2. Does your App use webviews? If your App uses Webviews to display HTML content it can usually be reverse-billed. Consider integrating the Datafree Reach solution to achieve this. Be aware that webviews often generate low level, background traffic you may not be aware of, for example fetching fonts, favicons etc., which may need to be explicitly handled. If your App consists primarily of a webview you could also consider using the Datafree WRAP product.
  3. Register with Datafree and modify the URLs in your App. (see sections above on how to achieve this)
  4. Is the connection datafree. A user’s connection is only datafree if they are using a mobile (not WiFi) connection with a Telco we have established a reverse billing relationship with. Using the Switch product we are able to establish whether the connection is datafree and we can forward this information to the Application’s backend servers in special HTTP headers (not for HTTPS requests).
  5. Warn the user if they are leaving datafree. To build user’s confidence that their session is datafree it is essential that you warn the user whenever they are switching to paying for the traffic. This may happen when people click on specific links in your App that, for example, opens a third party site in a browser, clicks on an ad or enters a part of your App you have determined should not be datafree. If there are actions that will result in data charges to your users then warnings should be added to your App. If you want to promote your App under the datafree banner then this is required behaviour.  
  6. Optimise your data consumption. You may think that your App is ‘data light’ but in our experience there is always data wastage in any App and data usage can always be improved. As a datafree App you are now paying for the data usage and consequently it is well worth reviewing all your network activity. 
  7. Return to the Datafree Portal and Register your App as Production. To help support your own App development process, the Switch interface maintains separate definition for the Development and Production versions of your App. When you are ready, set up your production settings in the Datafree Portal.  
  8. Avoid exploitation of your reverse billing. When you setup a reverse billing of data, others may try to exploit your account. The Datafree Platform inherently provides some protection through the registration of domains (an effective Whitelist) they but it also has specific items that can be set to provide further security and reassurance.  It is worth reviewing your specific environment to ensure you don’t pay for traffic that you don’t expect. As a minimum:   (a) Set daily spend limits within the Datafree Platform. (b) Set limits on the maximum size of any individual network request or content type being transferred.
  9. Integrate Datafree services. Integrating some common third party services into a Datafree App is not always possible. We have developed a number of common services that are fully reverse-billed and which can be easily integrated into your App. These include: Datafree Video Ads, Datafree Static Ads, Site Analytics and Extended Reporting