Developers

Codavel SDK (Beta)

Integration Overview

Codavel SDK is deployed via one component: Codavel Client (integrated into the mobile application)

The process of integrating our Codavel SDK with your application requires three main steps:

  1. Register at Codavel SDK and set up your private area
  2. Integrate Codavel Client with your mobile application

10,000 foot view of Bolina

Just before we kick-off this process, here are some deeper insights on Codavel SDK.

 

Codavel Client captures the app’s HTTP/HTTPS requests and sends those requests to a Codavel Server using a fast and efficient Bolina link.

 

Finally, the latter sends the response back to the mobile application in reverse order.

 

Bolina protocol establishes a fast and secure end-to-end connection between its peers, based on TLS 1.3. It fully supports HTTP or HTTPS requests, as well as HTTP/2.

Requirements

Mobile

Android

  • Minimum SDK version: 16

iOS

  • Minimum SDK version: 9.0 or higher

Step 1. Registering and setting up

To start the integration process, you need to register and validate your account at Codavel. If you haven’t registered yet, you can do it here (don’t forget to validate your account!). If you’re already registered, just log in.

Setting up basically consists of creating a deployment, which allows Codavel to identify and map all entities of your service. Each deployment is associated with a package, which defines the deployment usage, pricing plan and level of support.

Your deployment will be uniquely identified by a deployment ID (that maps clients with servers and validate licenses) and secret (that authenticates the server and clients). You can fetch both values from your private area, by creating a new deployment.

Creating a new deployment

    1. Go to the Home page of your private area and select New Deployment
      1. Choose a deployment name
      2. Set the application identifiers:
        1. Insert com.codavel.bolina.demo as the Android Package Name
        2. Insert com.codavel.bolina.demo as the iOS Bundle Identifier (available soon)
      3. Select the Free Tier package
      4. Select Create Deployment
    2. Fetch the deployment ID and secret from the created deployment
      1. Select the created deployment, or select the info icon of the created deployment
      2. Copy the deployment ID and secret

Note: Save the deployment ID and secret, they will be necessary to configure the Bolina Server and the mobile application.

Step 2. Integrating Codavel Client

Given that HTTP and HTTPS traffic must be captured on the app, Codavel Client is provided in an SDK that integrates with the most popular HTTP libraries used. It is now available for Android and iOS:

If your app does not use any of the previous HTTP libraries, Codavel Client SDK can also be used as a regular HTTP proxy, on both platforms, please contact us.

Android

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

On all approaches, you need to include the Codavel Client SDK repository to the app’s build.gradle, by adding the following lines:

allprojects {
        repositories {
            maven { url "https://artifact.codavel.com:8081/artifactory/android" }
        }
    }

OKHTTP v2.7+

If you’re integrating the Codavel Client SDK in an app that uses OKHTTP v2.7+, just import the library (don’t forget to import the repository first), by adding it to the build.gradle file:

...
implementation 'com.codavel.bolina:interceptor_okhttp2:0.9.39'

Then, enable Codavel SDK on the app after creating the OKHTTP client:

import com.codavel.bolina.interceptor.okhttp2.CvlOkHttp2Interceptor;
  ...
  OkHttpClient client = new OkHttpClient();
  client.interceptors().add(newCvlOkHttp2Interceptor();

Make sure that before performing HTTP requests, you import and start the interceptor by passing the application Context:

import com.codavel.bolina.interceptor.okhttp2.InterceptorSingleton;
  …
InterceptorSingleton.startInterceptor(getApplicationContext());

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

...
InterceptorSingleton.getInstance().stopInterceptor();
...

OKHTTP v3.0+

If you’re integrating Codavel Client SDK in an app that uses OKHTTP v3.0+, import the library (don’t forget to import the repository first), by adding it to the build.gradle file:

 android {
    defaultConfig {
        ...
        resValue "string", "BOLINA_DEPLOY_ID", ""
        resValue "string", "BOLINA_SECRET_ID", ""
    }
}
dependencies {
    ...
    implementation 'com.codavel.bolina:interceptor_okhttp3:0.9.39'
}

Then, enable Codavel SDK on the app when creating the OKHTTP client:

import com.codavel.bolina.interceptor.okhttp3.CvlOkHttp3Interceptor;
  ...
  OkHttpClient client = new OkHttpClient.Builder()
    .addInterceptor(new CvlOkHttp3Interceptor())
    .build();

Make sure that before performing HTTP requests you import and start the interceptor passing the application Context:

import com.codavel.bolina.interceptor.okhttp3.InterceptorSingleton;
 ...
InterceptorSingleton.startInterceptor(getApplicationContext());

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

...
InterceptorSingleton.getInstance().stopInterceptor();
...

HTTPURLConnection

If you’re integrating Codavel Client SDK in an app that uses HTTPURLConnection, import the library (don’t forget to import the repository first), by adding it to the build.gradle file:

android {
    defaultConfig {
        ...
        resValue "string", "BOLINA_DEPLOY_ID", ""
        resValue "string", "BOLINA_SECRET_ID", ""
    }
}
dependencies {
    ...
    implementation 'com.codavel.bolina:interceptor_urlconn3:0.9.39'
}

Then enable Codavel SDK on the app before performing an HTTP request:

  import com.codavel.bolina.interceptor.urlconn.InterceptorSingleton;
  ...
  InterceptorSingleton.startInterceptor(getApplicationContext());

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

...
InterceptorSingleton.getInstance().stopInterceptor();
...

Android HTTP Proxy

To use Codavel Client in proxy mode, the app must redirect all intended traffic to Codavel Client proxy, which is listening for HTTP requests on the localhost.

When Codavel 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 fast link, 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 integrate Codavel Client SDK as an HTTP proxy in an app, import the library (don’t forget to import the repository first) by adding it to the build.gradle file:

android {
    defaultConfig {
        ...
        resValue "string", "BOLINA_DEPLOY_ID", "<APP_ID>"
        resValue "string", "BOLINA_SECRET_ID", "<API_KEY>"
    }
}
dependencies {
    ...
    implementation 'com.codavel.bolina:proxy:0.9.5'
}

Then, enable Codavel Client proxy before any request by using the line:

ProxySingleton.startProxy(getApplicationContext());

To get the port where the Codavel Client proxy is listening for requests use the following line:

int port = ProxySingleton.getInstance().bolinaProxyPort

After enabling the Codavel Client proxy, all HTTP requests must be sent to the proxy that is listening for request on port on the localhost in the following format:

http://localhost:/?url=

All HTTP requests made to Codavel Client proxy must include a random token in an HTTP header with the name “Codavel-Token”. The token can be obtained after starting the service with the following line:

String token = ProxySingleton.getInstance().bolinaProxyToken

iOS

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

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_0.9.30.zip'
end

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

NSURLSession

If you’re integrating Codavel Client SDK in an app that uses NSURLSession, enable the Codavel Client (don’t forget to import the repository first) before any request (a good place would be the :didFinishLaunchingWithOptions: method in your AppDelegate):

...

Objective-c

    #import <BolinaInterceptor/BolinaInterceptor.h>

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


Swift

    #import  BolinaInterceptor

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

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

Objetive-c

    [BolinaInterceptor stopInterceptor];


Swift

    BolinaInterceptor.stop()

AFNetworking

If you’re integrating Codavel Client SDK in an app that uses AFNetworking, enable the Codavel Client (don’t forget to import the repository first) before any request (a good place would be the :didFinishLaunchingWithOptions: method in your AppDelegate):

#import <BolinaInterceptor/BolinaInterceptor.h>
    ...
    NSURLSessionConfiguration *configuration = [NSURLSessionConfiguration defaultSessionConfiguration];
    NSArray *protocols = [NSArray arrayWithObjects:[CdvlURLProtocol class], nil];
[configuration setProtocolClasses:protocols];

    AFURLSessionManager *manager = [[AFURLSessionManager alloc] initWithSessionConfiguration:configuration];

Then add the Bolina interceptor as a configuration of AFURLSessionManager and use that session manager to perform the HTTP requests:

#import <BolinaInterceptor/BolinaInterceptor.h>

    ...
    NSURLSessionConfiguration *configuration = [NSURLSessionConfiguration defaultSessionConfiguration];
    NSArray *protocols = [NSArray arrayWithObjects:[CdvlURLProtocol class], nil];
[configuration setProtocolClasses:protocols];

    AFURLSessionManager *manager = [[AFURLSessionManager alloc] initWithSessionConfiguration:configuration];

...

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

[BolinaInterceptor stopInterceptor];

iOS HTTP Proxy

To use Codavel Client in proxy mode, the app must redirect all intended traffic to  Codavel Client proxy, which is listening for HTTP requests on the localhost.

When Codavel Client works as an HTTP proxy, it does not accept HTTPS requests. To enable it would require certificate pinning, making its setup more complex. However, security is provided natively by the Bolina fast link, 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.

Bolina Proxy 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/BolinaProxy_0.9.7.zip'
end

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

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

To integrate Codavel Client SDK as an HTTP proxy in an app, after importing the repository, simply enable the Codavel Client proxy before any request (a good place would be the :didFinishLaunchingWithOptions: method in your AppDelegate):

Objective-c 

#import <BolinaProxy/BolinaProxy.h>
    ...
    int port = [BolinaProxy startProxy:@"<APP_ID>" withSecret:@"<APP_SECRET>"]

Swift

   import BolinaProxy

    let port = BolinaProxy.start(info.object(forKey: <APP_ID>) as? String, withSecret: info.object(forKey: <APP_SECRET>) as? String)

To ensure that the requests processed are only those sent by the entity that started the proxy, we required that all HTTP requests made to Codavel Client proxy include a random token in an HTTP header with the name “Codavel-Token”. The token can be obtained after starting the service with the following line:

After enabling the Codavel Client proxy, all HTTP requests must be sent to the proxy that is listening for request on port on the localhost in the following format:

Objective-c
NSString *token = [BolinaProxy getBolinaToken];


Swift
let token = BolinaProxy.getBolinaToken()

http://localhost:/?url=

Alamofire

If you’re integrating Codavel Client SDK in an app that uses Alamofire, enable the Codavel Client (don’t forget to import the repository first) before any request (a good place would be the :didFinishLaunchingWithOptions: method in your AppDelegate):

 #import BolinaInterceptor
    ...
     BolinaInterceptor.start(<APP_ID>, withSecret: <APP_SECRET>)

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

#import BolinaInterceptor

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

        manager = Alamofire.SessionManager(configuration: configuration)

...

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

BolinaInterceptor.stop()