Developers

Codavel Performance Service

Bolina On-Premises - Usage Guide

Requirements

Mobile

Android

  • Minimum SDK version: 16

iOS

  • Minimum SDK version: 9.0 or higher

Configure App

Before deploying all the necessary components to enable the Codavel Performance Service, an App must be configured in Codavel’s private area. In case you have already configured your App, you may skip this section. Otherwise, please follow these steps:

 

1. Login into https://private.codavel.com/

a. If you do not have access, please contact your dedicated account manager, he will give you access to the console.

2. Add a new app

a. Go to Home and click NEW APP

b. Fill in the fields, namely

 

      1. Give the app a name (descriptive)
      2. Add the package name (Android) and/or bundle identifier (iOS) of your app. If it doesn’t match with your app, the traffic will be discarded.
      3. Choose the App Type on-premises to use bolina on your own infrastructure
      4. Click in the button CREATE APP

3. The deployment is ready to use. The creation status should say Deployment ready, and you should receive an email notification shortly.

4. Click the app info button (?) to see the deployment id and the deployment secret

5. Take note of both deployment id and secret, you will need them later.

Integrate Mobile SDK

Bolina Mobile SDK consists of a service that listens for HTTP requests, translating those requests into Bolina Protocol and redirecting them to the desired Bolina Server. In case you use one of the most common HTTP libraries, Bolina automatically intercepts the HTTP requests, requiring no extra configuration.

→ Android

On Android, Bolina Client SDK can be integrated directly into the following HTTP libraries:

  • OKHttp3
  • HTTPURLConnection

Alternatively, Bolina Client SDK can also run in Proxy Mode, where the requests must be manually sent to the service.

Integration

OkHttp v3.0+

  • To add the Bolina Client SDK repository to your project, simply open the app build.gradle and add the following block of code:

repositories {

(...)

 maven { url 'https://artifact.codavel.com:8081/artifactory/android'}

(...)

}

  • Add the Bolina Client SDK as dependencies of the project and add the app id and app secret to the app’s build.gradle script:

android {

(...)

defaultConfig {

(...)

resValue "string", "BOLINA_DEPLOY_ID", "<Deployment_ID>"

resValue "string", "BOLINA_SECRET_ID", "<Deployment_Secret>"

(...)

}

(...)

}

dependencies {

(...)

implementation 'com.codavel.bolina:interceptor_okhttp3:<VERSION>'

(...)

}

The most recent version, is available in the private area, inside instructions.

  • Make sure that, before performing any HTTP request, you import and start the interceptor:

1. Import Bolina interceptor

 

import com.codavel.bolina.interceptor.okhttp3.InterceptorSingleton;

 

2. Initialize the Bolina Configuration and set the Bolina Configuration domain name

 

BolinaConfiguration config = new BolinaConfiguration();

 

config.setDomainName("<BOLINA_SERVER_URL>");

 

3. [optional] Configure your Origin.

 

config.addBolinaURLReplacement(“<your.cdn.com>”, “ <your.origin.com>”);

With this configuration, all requests intercepted by Bolina that would originally be sent to <your.cdn.com>, will be sent to a Bolina Server, that then will fetch the resource from <your.origin.com>. In case the Bolina transfer fails, the requests will be sent to <your.cdn.com>, as before. You can add multiple entries to be replaced. Otherwise, without this configuration, Codavel Performance Service servers will perform the same request as your HTTP clients would, to your current CDN or Origin.

 

4. Start the Bolina interceptor

 

InterceptorSingleton.startInterceptor(Context context, BolinaConfiguration config);

  • Create an OkHttpClient with Bolina interceptor already included:

import com.codavel.bolina.interceptor.okhttp3.CvlOkHttp3;

(...)

okhttpclient = CvlOkHttp3.registerBolina(okhttpclient);

(...)

  • [alternatively] Add the Bolina Interceptor to your OkHttpClient:

import com.codavel.bolina.interceptor.okhttp3.CvlOkHttp3;

(...)

OkHttpClient client =  CvlOkHttp3.clientBuilderWithBolina().build();

(...)

  • You should also stop the interceptor whenever you don’t need it, by running:

InterceptorSingleton.getInstance.stopInterceptor();

HTTPURLConnection

  • To add the Bolina Client SDK repository to your project, simply open the app build.gradle and add the following block of code:

repositories {

(...)

 maven { url 'https://artifact.codavel.com:8081/artifactory/android'}

(...)

}

  • Add the Bolina Client SDK as a dependency of the project and add the app id and app secret to the app’s build.gradle script:

android {

(...)

defaultConfig {

(...)

resValue "string", "BOLINA_DEPLOY_ID", "<Deployment_ID>"

resValue "string", "BOLINA_SECRET_ID", "<Deployment_Secret>"

(...)

}

(...)

}

dependencies {

(...)

implementation 'com.codavel.bolina:interceptor_urlconn:<VERSION>'

(...)

}

  • Before performing HTTP requests, import and start the interceptor as follows:

1. Import Bolina interceptor

 

import com.codavel.bolina.interceptor.urlconn.InterceptorSingleton;

 

2. Initialize the Bolina Configuration and set the Bolina Configuration domain name

 

BolinaConfiguration config = new BolinaConfiguration();

config.setDomainName("<BOLINA_SERVER_URL>");

 

3. [optional] Configure your Origin.

 

config.addBolinaURLReplacement(“<your.cdn.com>”, “ <your.origin.com>”);

With this configuration, all requests intercepted by Bolina that would originally be sent to <your.cdn.com>, will be sent to a Bolina Server, that then will fetch the resource from <your.origin.com>. In case the Bolina transfer fails, the requests will be sent to <your.cdn.com>, as before. You can add multiple entries to be replaced. Otherwise, without this configuration, Codavel Performance Service servers will perform the same request as your HTTP clients would, to your current CDN or Origin.

 

4. Start the Bolina interceptor:

 

InterceptorSingleton.startInterceptor(Context context, BolinaConfiguration config);

  • You should also stop the interceptor whenever you don’t need it, by running:

InterceptorSingleton.getInstance().stopInterceptor();

Proxy

In case we do not have a custom interceptor for your HTTP client, you may use Bolina Mobile SDK in proxy mode. In this mode, the App must redirect all intended traffic to Bolina Client proxy, which is listening for HTTP requests on the localhost. When Bolina Client works as an HTTP proxy, it does not accept HTTPS requests. Enabling it would require certificate pinning, making its setup more complex. However, security is provided natively by the Bolina protocol, given that it provides end-to-end encryption based on TLS 1.3. No changes are required on the original Content Server side, given that Bolina Server will send regular HTTPS requests to the original Content Server.

  • To add the Bolina Client SDK repository to your project, simply open the app build.gradle and add the following block of code:

repositories {

(...)

 maven { url 'https://artifact.codavel.com:8081/artifactory/android'}

(...)

}

  • Add the Bolina Client SDK as a dependency of the project and add the app id and app secret to the app’s build.gradle script.

android {

(...)

defaultConfig {

(...)

resValue "string", "BOLINA_DEPLOY_ID", "<Deployment_ID>"

resValue "string", "BOLINA_SECRET_ID", "<Deployment_Secret>"

(...)

}

(...)

}

dependencies {

(...)

implementation 'com.codavel.bolina:proxy:<VERSION>'

(...)

}

The most recent version, is available in the private area, inside instructions.

  • Before performing HTTP requests, import and start the proxy as follows:

1. Import Bolina proxy

 

import com.codavel.bolina.proxy.ProxySingleton;

 

2. Initialize the Bolina Configuration and set the Bolina Configuration domain name

 

BolinaConfiguration config = new BolinaConfiguration();
config.setDomainName("<BOLINA_SERVER_URL>");

 

3. [optional] Configure your Origin

 

config.addBolinaURLReplacement(“<your.cdn.com>”, “ <your.origin.com>”);

 

With this configuration, all requests intercepted by Bolina that would originally be sent to <your.cdn.com>, will be sent to a Bolina Server, that then will fetch the resource from <your.origin.com>. In case the Bolina transfer fails, the requests will be sent to <your.cdn.com>, as before. You can add multiple entries to be replaced. Otherwise, without this configuration, Codavel Performance Service servers will perform the same request as your HTTP clients would, to your current CDN or Origin.

 

4. Start the Bolina proxy

 

ProxySingleton.startProxy(Context context, config);

 

5. Store the port where Bolina proxy is listening for requests:

 

String port = ProxySingleton.getInstance().bolinaProxyPort;

 

Add Codavel security token to HTTP request header with the name “Codavel-Token”. The token can be obtained with the following line:

 

String token = ProxySingleton.getInstance().bolinaProxyToken;

 

Send HTTP request to the service but changing the desired request to the following format:

 

http://localhost:<port>/?url=<original_url>

 

You should also stop the proxy whenever you don’t need it, by running:

 

ProxySingleton.getInstance().stopProxy();

  • Add Codavel security token to HTTP request header with the name “Codavel-Token”. The token can be obtained with the following line:

String token = ProxySingleton.getInstance().bolinaProxyToken;

  • Send HTTP request to the service but changing the desired request to the following format:

http://localhost:<port>/?url=<original_url>

  • You should also stop the proxy whenever you don’t need it, by running:
ProxySingleton.getInstance().stopProxy();

Confirgure actions in App

Bolina SDK can collect the performance data between two points in your app code. This way you can easily compare the network performance of the app requests with and without bolina in a dashboard in your Bolina Performance Console. Bolina SDK provides a method to start the trace of an action, another one to stop the trace, and another one to add optional metadata.

 

1. When you want to mark the start of an action, add the following line to your code

 

String action_id = InterceptorSingleton.getInstance().startAction(“open app”, (bolina ? "BOLINA" : "HTTP"));

 

2. When you want to mark the stop of the same action, add the following line to your code:

 

InterceptorSingleton.getInstance().stopAction(action_id);

 

3. When you want to add metadata to the action, add the following lines to your code:

 

JSONObject metadata = new JSONObject();

metadata.put(“test”,”testing-metadata”);

metadata.put(“test_int”,123);

InterceptorSingleton.getInstance().addActionMetadata(action_id,metadata);

 

4. When you finish collecting data to the action, add the following line to your code:

 

InterceptorSingleton.getInstance().processAction(action_id);

 

Example:

Trace the time to start a video:

  1. Call startAction when the user press the play button and give it a name, e.g. “video start”
  2. Call stopAction when the video starts playing
  3. Call processAction to save the action and send the action stats to your dashboard

Advanced Configurations

Bolina SDK allows the configuration of some advanced settings for enabling some features, configuring security options and increasing the debug level. Please, before changing these settings make sure you know what you are doing. All the methods below are accessible via the BolinaConfiguration object that you need to pass to InterceptorSingleton.startInterceptor()

 

 

App settings

 

  • addBolinaURLReplacement(String originalURLRegex, String bolinaURL) – Adds a new rule to be executed at each HTTP request. If the URL matches the expression configured, then Bolina will replace the matched expression with the configured URL. In case of Bolina fallback, the original URL will be used
  • addFallbackURLReplacement(String bolinaURLRegex, String originalURL) – Adds a new rule to be executed in case of Bolina fallback or performing A/B testing. If the URL used by bolina matches the expression configured, then Bolina will replace the matched expression with the configured URL.
  • setConfigFolder(String configFolder) – Sets the path used by Bolina core to store cached info. Default: application specific cache directory on the filesystem.

 

A/B testing settings

 

  • setUseABTestingPerSession(boolean useABTestingPerSession) – Enables or disables the ab testing per session. This flag changes the behavior of setABTestPercentage. When this flag is set to true, the ab test percentage is calculated per session, otherwise, it is calculated per request. Here we assume a session is a new app start. Default: false
  • setABTestPercentage(int abTestPercentage) – Sets the percentage of requests or sessions using Bolina. Should be used with setUseABTestingPerSession to define if the ab testing is per session or per request. Default: 100 , meaning all requests or all sessions are using Bolina.

 

Verbose settings

 

  • setVerboseLevel(String verboseLevel) – Changes the verbose level of Bolina client. Accepted values: “critical”(less logs), “info”, “debug”, “trace”(more logs). Default: critical

 

Protocol settings

 

  • setBolinaHandlerPattern(Pattern bolinaHandlerPattern) – Sets the URLs to be handled via bolina. Any URL that match this pattern will use bolina, on the other hand, a URL that does not match this pattern will be transferred using regular HTTP. default: Pattern.compile(“.*”), meaning all requests are accelerated
  • setCertsEnabled(boolean enableCerts) – Enables/Disable the use of SSL certificates. Default: true.
  • setAllowSelfSignedCerts(boolean allowSelfSignedCerts) – Enables/Disable the use of self signed SSL certificates. We strongly recommend the use of this option only for testing purposes. Default: false. 
  • setMaxMemoryAllowed(long maxMemoryAllowed) – Sets the maximum amount of memory used by bolina core. Default: 10MB
  • setZeroRtt(boolean enableZeroRtt) – Enables or disables the use of 0-RTT in Bolina. Default: enabled
  • setTimeToKeepAlive(int timeToKeepAlive) – Sets the maximum time that a connection will be kept alive, in milliseconds. Default: 120s

 

Insights settings

 

  • setMonitorPercentage(int monitorPercentage) – Sets the percentage of requests to be traced for detailed statistics in the insights dashboard. A value of 100 means all requests appear in the dashboard. Default: 100

→ iOS

On iOS, Bolina Client SDK can be integrated directly into the following HTTP libraries:

  • NSURLSession
  • AFNetworking
  • Alamofire

 

On all approaches, Bolina Interceptor is distributed using CocoaPods, a dependency manager for Objective-c and Swift. To install CocoaPods run the following commands in Terminal.app:

 

sudo gem install cocoapods

pod setup

 

Then, you’ll need to create a file named ‘Podfile’ in the same directory as your Xcode project (.xcodeproj) file with the following content:

 

target "MyTargetName" do

     platform :ios, '9.0'

     use_frameworks!

     pod 'BolinaInterceptor', :http=>'https://artifact.codavel.com:8081/artifactory/ios/BolinaInterceptor_<VERSION>.zip'
end 

The most recent version, is available in the private area, inside instructions.

Now you can install the dependencies in your project using the command:

 

pod install

 

To build your app with the dependencies, you need to open the generated Xcode workspace (.xcworkspace) instead of the project file:

 

open <YourProjectName>.xcworkspace

Integration

URLSession

If you’re integrating Bolina Client SDK in an app that uses URLSession, enable the Bolina Client before any request (a good place would be the :didFinishLaunchingWithOptions: method in your AppDelegate):

Objective-c

 

1. Import Bolina interceptor

 

#import <BolinaInterceptor/BolinaInterceptor.h>

 

2. Initialize the Bolina Configuration and set the Bolina Configuration domain name

 

BolinaConfiguration *config = [BolinaConfiguration initBolinaConfiguration];

[config setDomain:@"<BOLINA_SERVER_URL>"];

 

3. [optional] Configure your Origin.

 

[config addBolinaURLReplacement:@“<your.cdn.com>” url:@“ <your.origin.com>”];

 

With this configuration, all requests intercepted by Bolina that would originally be sent to <your.cdn.com>, will be sent to a Bolina Server, that then will fetch the resource from <your.origin.com>. In case the Bolina transfer fails, the requests will be sent to <your.cdn.com>, as before. You can add multiple entries to be replaced. Otherwise, without this configuration, Codavel Performance Service servers will perform the same request as your HTTP clients would, to your current CDN or Origin.

 

4. Start the Bolina interceptor

 

[BolinaInterceptor startInterceptor:@"<APP_ID>" withSecret:@"<APP_SECRET>"];

 

5. Make sure you stop the interceptor whenever you don’t need it:

 

[BolinaInterceptor stopInterceptor];

 

Swift

1. Import Bolina interceptor

 

#import  BolinaInterceptor

 

2. Initialize the Bolina Configuration and set the Bolina Configuration domain name

 

let config = BolinaConfiguration.initBolinaConfiguration() as! BolinaConfiguration
config.setDomain("<BOLINA_SERVER_URL>")

 

3. [optional] Configure your Origin.

 

config.addBolinaURLReplacement(“<your.cdn.com>”, url:“ <your.origin.com>”);

 

With this configuration, all requests intercepted by Bolina that would originally be sent to <your.cdn.com>, will be sent to a Bolina Server, that then will fetch the resource from <your.origin.com>. In case the Bolina transfer fails, the requests will be sent to <your.cdn.com>, as before. You can add multiple entries to be replaced. Otherwise, without this configuration, Codavel Performance Service servers will perform the same request as your HTTP clients would, to your current CDN or Origin.


4. Start the Bolina interceptor

 

BolinaInterceptor.start("<APP_ID>", withSecret: "<APP_SECRET>", with: config)

 

5. Make sure you stop the interceptor whenever you don’t need it:

 

BolinaInterceptor.stop()

 

AFNetworking

 

If you’re integrating Bolina Client SDK in an app that uses AFNetworking, enable the Bolina Client before any request (a good place would be the :didFinishLaunchingWithOptions: method in your AppDelegate):

1. Import Bolina headers

 

#import <BolinaInterceptor/BolinaInterceptor.h>

#import <BolinaInterceptor/BolinaConfiguration.h>

#import <BolinaInterceptor/CdvlURLProtocol.h>

 

2. Initialize the Bolina Configuration and set  the Bolina Configuration domain name

 

BolinaConfiguration *config = [BolinaConfiguration initBolinaConfiguration];

[config setDomain:@"<BOLINA_SERVER_URL>"];

 

3. [optional] Configure your Origin.

 

[config addBolinaURLReplacement:@“<your.cdn.com>” url:@“ <your.origin.com>”];

 

With this configuration, all requests intercepted by Bolina that would originally be sent to <your.cdn.com>, will be sent to a Bolina Server, which then will fetch the resource from <your.origin.com>. In case the Bolina transfer fails, the requests will be sent to <your.cdn.com>, as before. You can add multiple entries to be replaced. Otherwise, without this configuration, Codavel Performance Service servers will perform the same request as your HTTP clients would, to your current CDN or Origin.

4. Start the Bolina interceptor

 

[BolinaInterceptor startInterceptor:@"<APP_ID>" withSecret:@"<APP_SECRET>"];

 

5. Add the Bolina interceptor as a configuration of AFURLSessionManager and use that session manager to perform the HTTP requests:

 

NSURLSessionConfiguration *configuration = [NSURLSessionConfiguration defaultSessionConfiguration];
NSArray *protocols = [NSArray arrayWithObjects:[CdvlURLProtocol class], nil];
[configuration setProtocolClasses:protocols];
AFURLSessionManager *manager = [[AFURLSessionManager alloc] initWithSessionConfiguration:configuration];

 

6. Make sure you stop the interceptor whenever you don’t need it:

 

[BolinaInterceptor stopInterceptor];

 

Alamofire

If you’re integrating Bolina Client SDK in an app that uses Alamofire, enable the Bolina Client before any request (a good place would be the :didFinishLaunchingWithOptions: method in your AppDelegate):

 

1. Import Bolina interceptor

 

import BolinaInterceptor

 

2. Initialize the Bolina Configuration and set the Bolina Configuration domain name

 

let config = BolinaConfiguration.initBolinaConfiguration() as! BolinaConfiguration
config.setDomain("<BOLINA_SERVER_URL>")

 

3. [optional] Configure your Origin.

 

config.addBolinaURLReplacement(“<your.cdn.com>”, url: “ <your.origin.com>”);

 

With this configuration, all requests intercepted by Bolina that would originally be sent to <your.cdn.com>, will be sent to a Bolina Server, that then will fetch the resource from <your.origin.com>. In case the Bolina transfer fails, the requests will be sent to <your.cdn.com>, as before. You can add multiple entries to be replaced. Otherwise, without this configuration, Codavel Performance Service servers will perform the same request as your HTTP clients would, to your current CDN or Origin.

 

4. Start the Bolina interceptor

 

BolinaInterceptor.start("<APP_ID>", withSecret: "<APP_SECRET>", with: config)

 

5. Add the Bolina interceptor as a configuration of Alamofire.SessionManager and use that session manager to perform the HTTP requests:

 

let configuration = URLSessionConfiguration.default
if configuration.protocolClasses != nil {
configuration.protocolClasses!.insert(CdvlURLProtocol.self, at: 0)
}
manager = Alamofire.Session(configuration: configuration)

 

6. Make sure you stop the interceptor whenever you don’t need it:

 

BolinaInterceptor.stop()

Configure Actions in App

Bolina SDK can collect the performance data between two points in your app code. This way you can easily compare the network performance of the app requests with and without Bolina in a dashboard in your Bolina Performance Console. Bolina SDK provides a method to start the trace of an action, another one to stop the trace, and another one to add optional metadata.

Objective-c

 

1. When you want to mark the start of an action, add the following line to your code

 

NSString *action_id = [BolinaInterceptor startAction:@"action" withProtocol:@"Bolina"];

 

2. When you want to mark the stop of the same action, add the following line to your code:

 

[BolinaInterceptor stopAction:action_id];

 

3. When you want to add metadata to the action, add the following lines to your code:

 

NSMutableDictionary *metadata = [[NSMutableDictionary alloc] init];
[metadata setValue:@"testing-metadata" forKey:@"test"];
[metadata setValue:[NSNumber numberWithInt:123] forKey:@"test_int"];

[BolinaInterceptor addActionMetadata:action_id withMetadata:metadata];

 

4. When you finish collecting data to the action, add the following line to your code:

 

[BolinaInterceptor processAction:action_id];

Swift

 

1. When you want to mark the start of an action, add the following line to your code

 

let demoActionId = BolinaInterceptor.startAction("test_ios", withProtocol: "Bolina")

 

2. When you want to mark the stop of the same action, add the following line to your code:

 

BolinaInterceptor.stopAction(action_id)

 

3. When you want to add metadata to the action, add the following lines to your code:

 

let json:NSMutableDictionary = [:]

json["test_int"] = 123

json["test"] = "testing-metadata"

BolinaInterceptor.addActionMetadata(action_id, withMetadata: json)

 

4. When you finish collecting data to the action, add the following line to your code:

 

BolinaInterceptor.processAction(demoActionId)

 

Example:

 

Trace the time to start a video:

1. Call startAction when the user press the play button and give it a name, e.g. “video start”

2. Call stopAction when the video start playing

3. Call processAction to save the action

Advanced Configurations

Bolina SDK allows the configuration of some advanced settings for enabling some features, configuring security options and increasing the debug level. Please, before changing these settings make sure you know what you are doing. All the methods below are accessible via the BolinaConfiguration object that you need to pass to InterceptorSingleton.startInterceptor()

 

App settings

 

setConfigFolder(String configFolder) – Sets the path used by bolina core to store cached info. Default: application specific cache directory on the filesystem.

 

A/B testing settings

 

setUseABTestingPerSession(boolean useABTestingPerSession) – Enables or disables the ab testing per session. This flag changes the behaviour of setABTestPercentage. When this flag is set to true, the ab test percentage is calculated per session, otherwise it is calculated per request. Here we assume a session is a new app start. Default: false

 

setABTestPercentage(int abTestPercentage) – Sets the percentage of requests or sessions using Bolina. Should be used with setUseABTestingPerSession to define if the ab testing is per session or per request. Default: 100 , meaning all requests or all sessions are using bolina

 

Verbose settings

 

setVerboseLevel(String verboseLevel) – Changes the verbose level of bolina client. Accepted values: “critical”(less logs), “info”, “debug”, “trace”(more logs). Default: critical

 

Protocol settings

 

setBolinaHandlerPattern(Pattern bolinaHandlerPattern) – Sets the URLs to be handled via bolina. Any URL that match this pattern will use bolina, on the other hand, a URL that does not match this pattern will be transferred using regular HTTP. default: Pattern.compile(“.*”), meaning all requests are accelerated

 

setCertsEnabled(boolean enableCerts) – Enables/Disable the use of SSL certificates. Default: true.

 

setAllowSelfSignedCerts(boolean allowSelfSignedCerts) – Enables/Disable the use of self signed SSL certificates. We strongly recommend the use of this option only for testing purposes. Default: false.

 

setMaxMemoryAllowed(long maxMemoryAllowed) – Sets the maximum amount of memory used by bolina core. Default: 10MB

 

setZeroRtt(boolean enableZeroRtt) – Enables or disables the use of 0-RTT in Bolina. Default: enabled

 

setTimeToKeepAlive(int timeToKeepAlive) – Sets the maximum time that a connection will be kept alive, in milliseconds. Default: 120s

 

Insights settings

 

– setMonitorPercentage(int monitorPercentage) – Sets the percentage of requests to be traced for detailed statistics in the insights dashboard. A value of 100 means all requests appear in the dashboard. Default: 100