Technical Guidelines

While smartphones are increasingly available around the world, the majority of people in emerging markets still have feature phones. To ensure that Free Basics is accessible to all, we focus on supporting lightweight mobile websites.

Details

In order to make your website display properly within the Free Basics Platform and be accessible to people on all types of phones and data plans, your mobile website(s) must meet certain technical conditions created by the Free Basics proxy. Specifically, mobile websites should work in the absence of:

  • JavaScript
  • iframes
  • Video and large images
  • Flash and Java applets

If websites are found to contain any of the above post-implementation, we will block them until we can confirm that the content has been removed.

JavaScript

In order to offer an experience that can work across devices, your service should remain functional and useful when JavaScript is disabled. This means that your content should not rely on JavaScript for any of the core user experiences, particularly navigation or other core functionality.

iframes

Some suppression may occur for iframes so make sure that your content doesn’t rely on them. We recommend avoiding iframes altogether as it tends to lessen a mobile experience.

Video and large images

To respect low-data consumption for people using Free Basics, please avoid large data-consuming resources such as video and high definition images. We will not display video files and will also truncate resources larger than 200 KB.

Flash and Java applets

Free Basics does not support Flash resources or Java applets. If your service makes use of these technologies, please ensure to implement proper fallbacks so that they are hidden appropriately and don’t disrupt the functionality of your site.

HTTPS support

We encrypt information for Free Basics wherever possible. When people use the Free Basics Android app, their traffic is encrypted end-to-end unless you specify that your service should be HTTP only. For the Free Basics website in a mobile browser, we use a “dual certificate” model to encrypt traffic between a person's device and our servers in both directions. If your server supports HTTPS, we will also encrypt traffic between our servers and yours. Even if your service doesn't yet support HTTPS, where possible we will encrypt that information between our servers and people's devices unless you ask us to not use dual certificate HTTPS. When people use the Free Basics mobile website, information is temporarily decrypted on our secure servers to ensure proper functionality of the services and to avoid unexpected charges to people.

We preserve the privacy of that information while it's decrypted by only storing the domain name of your service and the amount of data being used—the same information that would be visible using end-to-end encryption—as well as cookies that are stored in an encrypted and unreadable format.

Internet.org Proxy

From within Free Basics, all traffic is routed through the Internet.org proxy. We do this in order to create a standard traffic flow so that operators can properly identify and zero rate your service. It is important to realize that your service is neither hosted nor cached by Internet.org — it still operates on your own servers and is completely maintainable by you — and by detecting requests that pass through the Free Basics Platform, you can apply controls such as geo-blocking for your content and/or measure your Free Basics Platform traffic.

IP Addresses

  • Be aware that, because of the SSL encryption, the Free Basics Android app does not support the x-iorg-fbs-uip and x-iorg-fbs HTTP header fields.

Since requests pass through the Internet.org proxy, the HTTP Request IP address will always be from our servers instead of from the original requestor. You can obtain the original requestor IP from X-IORG-FBS-UIP HTTP header field (which is created by our proxy).

Our proxy also follows the X-Forwarded-For convention, so the same IP address will be found in that field as well (as a first non-private IP address).

Detecting Requests

All requests that pass through the Internet.org proxy will contain X-IORG-FBS field (always set to true). It's enough to just check for its existence inside the header.

Apart from that, the string Internet.org is inserted into the Via header field, which is a secondary way to identify requests which have passed through our proxy.

All requests coming from the Android app will contain a unique user-agent HTTP header value (which depends on the app version). An example of such user-agent is:

Mozilla/5.0 (Linux; Android 7.1.2; Pixel Build/N2G47E; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/57.0.2987.132 Mobile Safari/537.36[FBAN/InternetOrgApp; FBAV/7.0;]

In order to detect the request, you can check if the string contains “InternetOrgApp”

Cookies

Cookies are supported.

User Agent (UA String)

The UA String from the original requestor is not altered by the Internet.org proxy.

Analytics and Measurement

You may use tracking services, such as Google Analytics, Effective Measure, Chartbeat, etc. on your site. As mentioned above, our web environment does not support JavaScript at this time and this is important to be aware of, since many analytics services rely on JavaScript for their full functionality — though most provide a fallback for when JavaScript is not available. Please consult the documentation of any service(s) you are using.

Google Analytics

To make it easier to use Google Analytics without JavaScript inside Free Basics Platform, below are some guidelines on setting up your service.

Detecting country

To correctly detect user's country, you need to correctly fill the UIP override parameter for Google Analytics request. The easiest way to do so is to utilize X-IORG-FBS-UIP HTTP header field (see Internet.org proxy). The UIP parameter would have to be set server-side for the request to Google Analytics.

Tracking without JavaScript

To perform traffic analysis without JavaScript you will need to utilize the server-side of your service.

Google Analytics requests can be managed completely by back-end, and the server can take care of managing cookies (or distinguishing users in some other way). You can decide which parameters of request to fill out and use for analytics. This is done using Google Analytics Measurement Protocol.

If you already had am iframe solution, what you will need to do is to do a POST request on your server-side to the Google Analytics address. Most of the parameters will be consistent with those used by iframe solution.

Testing

Before you submit your website for consideration, you should test it through all the requirements above. The following resources can help provide you with real-time feedback on your readiness.

Chrome Device Emulator

The Chrome Browser can emulate a mobile experience, which greatly facilitates most aspects of testing. We recommend turning on Device Emulation and testing your entire site with the following:

Instructions can be found here: https://developer.chrome.com/devtools/docs/device-mode

Opera Emulator

Opera provides an emulator of their own which allows for more specific testing of how your site renders and behaves on the Opera Mini browser.

Instructions can be found here: http://dev.opera.com/articles/installing-opera-mini-on-your-computer/