Welcome to the 21YB Acceleration Tunnel Integration Guide for Android. This guide will help you seamlessly integrate the 21YB Acceleration Tunnel into your Android project. Before you begin, follow the steps below to get started.

Quick Start

1. Obtain the Starter Package

To begin the integration process, you’ll need to obtain the starter code package and a test yb_uid from your account manager. If you haven’t received these, please contact your account manager to get started.

Setup and Run

2. Install swig

For macOS users:

brew install swig
swig -version

For Windows users:

  1. Download the executable file from
  2. Add the path to the SWIG executable to your system’s environment variables within Android Studio.

3. Configure the Starter

Open the yb-tunnelkit-android package in Android Studio.

For Windows users, modify the following line in openvpn/src/main/cpp/CMakeLists.txt:

set(SWIG_EXECUTABLE "swig") 


set(SWIG_EXECUTABLE "swig.exe") 

This adds the .exe suffix for the SWIG executable.

After completing these steps, you’ll be ready to run the starter on your Android devices.

Core Methods Explanation

Tunnel Connection Flow

  1. Authentication: Begin by logging in or registering using the 21YunBox SMS/Auth APIs.
  2. Obtain yb_uid: Upon successful authentication, obtain a unique yb_uid.
  3. Connecting to Firebase: To access Firebase, use the prepareVpn() method, which will trigger connect() after obtaining user permissions.

Connect to the Tunnel

After obtaining a yb_uid from the Auth API, pass it to our server to load the connection configuration. Here’s an example of how to connect to the tunnel using yb_uid:

private void connect() {
    // TODO: Update ybUID. Refer to 21YunBox Auth API, '/check-code' for production ybUID.
    String ybUID = "your_yb_uid";
    Utils.LoadConfigTask loadConfigTask = new Utils.LoadConfigTask(new Utils.FetchCallback() {
        public void onFetchComplete(String config) {
            try {
                APIVpnProfile profile = mService.addNewVPNProfile(VPNProfileName, false, config);
                // Add other logic once the VPN connection has started.
            } catch (RemoteException e) {
                // Handle connection failure

Disconnect the Tunnel Connection

To disconnect the tunnel, simply call disconnect():

public boolean disconnect() {
    try {
        // Add logic for when disconnected.
    } catch (RemoteException e) {
        // Handle connection failure
    return false;

Connection States

During the tunnel connection, you’ll encounter the following major connection states:

  • NOPROCESS: No network connection.
  • CONNECTED: Connected to the server.
  • WAIT: Awaiting server reply.
  • AUTH: Authenticating.
  • CONNECTRETRY: Waiting between connection attempts.
  • AUTH_FAILED: Authentication failed.
  • EXITING: Exiting; unable to connect to the server.

CONNECTED indicates that the tunnel is ready to serve traffic on your devices.

Trouble Shooting Guide

Q1: How do I know if I’m connecting to the tunnel?

Before connecting to the tunnel, follow these steps to verify your connection:

  1. Open a web browser on your device.
  2. Visit one of the following websites to check your IP address:

When you open these sites, they will display your current IP address.

Once you’re connected to the tunnel, perform the following steps to confirm your connection:

  1. Check your IP address again.
  2. If the connection is successful, your IP address should now reflect our tunnel IP address, not your original one.

For users of our starter kit, you can simply click the “Get my IP” button, and the IP address will be displayed in the console.

Note: Please be aware that the server is hosted in China, so if you are developing outside China, you may experience a 1-2 second delay depending on your location.

Q2: I’m encountering difficulties connecting to XYZ APIs or services while connected to the tunnel.

This issue is intentional and stems from the restricted access to certain services and APIs. Here’s what you can do:

  1. Review our allowed services and APIs list. If the service you need is not on the list, contact your account manager with a valid reason for accessing it. We will work with you to add the necessary IP addresses for access.

  2. For Firebase services, our system continuously updates our IP address database to ensure seamless connectivity. However, if you experience difficulties connecting to Firebase services in China, please reach out to your account manager. Explain the specific Firebase services you are having trouble with, and we will assist you from there.

Note: Access to new APIs or services may take some time due to the need to ensure compliance with Chinese laws. Please be patient during this process.

By following these troubleshooting steps, you can ensure a smoother experience while using our tunnel service. If you have further questions or issues, don’t hesitate to contact our support team. We are here to assist you.