Contents

Introduction

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 swig.org.
  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")

to

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() {
        @Override
        public void onFetchComplete(String config) {
            try {
                APIVpnProfile profile = mService.addNewVPNProfile(VPNProfileName, false, config);
                mService.startProfile(profile.mUUID);
                mService.startVPN(config);
                // Add other logic once the VPN connection has started.
            } catch (RemoteException e) {
                // Handle connection failure
            }
        }
    });
    loadConfigTask.execute(ybUID);
}

Disconnect the Tunnel Connection

To disconnect the tunnel, simply call disconnect():

public boolean disconnect() {
    try {
        mService.disconnect();
        // 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 myip.21cloudbox.com 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.

Q3: “Could not reach Cloud Firestore backend”. How do I resolve this?

Typically, you will see an error message like the following in your logs:

[FirebaseFirestore][I-FST000001] Could not reach Cloud Firestore backend. Backend didn't respond within 10 seconds.

This usually indicates that your device does not have a stable Internet connection at the moment. The client will operate in offline mode until it can successfully connect to the backend.

This error occurs when you attempt to read content from Firebase Firestore without being connected to the 21YB Tunnel. Ensure you follow the instructions above to connect to the tunnel. After verifying your connection, try reading from Firestore again.

If you still encounter the same message in your logs while the tunnel is active, please reach out to your account manager for further assistance.

Q4: Stream error: ‘Unavailable: failed to connect to all addresses’. How do I resolve this?

Typically, you will see an error message like the following in your logs:

[FirebaseFirestore][I-FST000001] WriteStream (13be526e8) Stream error: 'Unavailable: failed to connect to all addresses'

This error occurs when you attempt to write content to Firebase Firestore without being connected to the 21YB Tunnel. Ensure you follow the instructions above to connect to the tunnel. After verifying your connection, try writing to Firestore again.

If you still encounter the same message in your logs while the tunnel is active, please reach out to your account manager for further assistance.

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.

Ready to try 21YunBox?

Get Started