Android ConnectionBuddy

Provides a simple way of handling connectivity change events.

Usage

1. Add the library as a dependency to your build.gradle

compile 'com.zplesac:connectionbuddy:version@aar'

Check the latest version here.

Versions prior to 1.0.5 were hosted on an older jCenter repository and aren't available anymore due to trademark issues.

2. Initialize a ConnectionBuddy instance in your Application class. You'll also need to provide a global configuration by defining ConnectionBuddyConfiguration object.

public class SampleApp extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
         ConnectionBuddyConfiguration networkInspectorConfiguration = new ConnectionBuddyConfiguration.Builder(this).build();
         ConnectionBuddy.getInstance().init(networkInspectorConfiguration);
    }
}

All options in ConnectionBuddyConfiguration.Builder are optional. Use only those you really want to customize.

3. Make your activites (or BaseActivity) extend ConnectionBuddyActivity, and react to connectivity change events in onConnectionChange(ConnectivityEvent event) callback method:

  @Override
  public void onConnectionChange(ConnectivityEvent event) {
      if(event.getState() == ConnectivityState.CONNECTED){
          // device has active internet connection
      }
      else{
         // there is no active internet connection on this device
      }
  }

If you don't want to extend ConnectionBuddyActivity, you can use manual configuration:

• Register to connectivity change events in the onStart() method of your activity:

 @Override
 protected void onStart() {
     super.onStart();
     ConnectionBuddy.getInstance().registerForConnectivityEvents(this, this);
}

• Unregister from connectivity change events in the onStop() method of your activity:

  @Override
  protected void onStop() {
      super.onStop();
      ConnectionBuddy.getInstance().unregisterFromConnectivityEvents(this);
  }

• Clear the stored connectivity state for your activity/fragment if it was restored from a saved instance state (in order to always have the latest connectivity state). Add to your onCreate() method the following line of code:

  @Override
  protected void onCreate(Bundle savedInstanceState) {
       super.onCreate(savedInstanceState);

       ...

       if(savedInstanceState != null){
           ConnectionBuddyCache.clearInternetConnection(this);
       }
   }

• Implement a ConnectivityChangeListener interface and react to connectivity change events.

ConnectivityEvent also holds some additional information:

• ConnectivityType enum, which defines the network connection type currently available on the user's device
• ConnectivityStrength enum, which describes signal strength of the network connection.

ConnectionBuddy configuration

You can customize the default ConnectionBuddy configuration by providing your own configuration. Following values can be changed:

1. registerForWiFiChanges(boolean shouldRegister)

A Boolean value which defines whether we should register for WiFi network changes. The default value is set to true.

2. registerForMobileNetworkChanges(boolean shouldRegister)

A Boolean value which defines whether we should register for mobile network changes. The default value is set to true.

3. setMinimumSignalStrength(ConnectivityStrength minimumSignalStrength)

Defines the minimum signal strength for which the callback listener should be notified. The default value is set to ConnectivityStrength.POOR.

4. setNotifyImmediately(boolean shouldNotify)

A Boolean value which defines whether we want to notify the listener about the current network connection state immediately after the listener has been registered. The default value is set to true.

5. notifyOnlyReliableEvents(boolean shouldNotify)

A Boolean value which defines whether we want to use reliable network events. If we have an active internet connection, it will try to execute a test network request to determine whether a user is capable of any network operation. The default value is set to false.

Advanced usage with MVP pattern

ConnectionBuddy also provides ConnectivityPresenter which can be used as a base presenter for registering to connectivity change events. A more detailed example can be found here.

Backward compatibility

As of version 1.2.0, ConnectionBuddy can be used with your apps on devices all the way back to Android 2.3 (API 10). It should also work on devices with API 8-9, but that's not tested.

Changelog

Changelog is available in the releases tab.

For versions prior to 2.0.0, here.

Contributing

Feedback and code contributions are very much welcome. Just make a pull request with a short description of your changes. By making contributions to this project you give permission for your code to be used under the same license.