@abl-solutions/wifi-connect

WiFi Connect - React Native SDK

React Native SDK to configure and use WiFi networks managed and operated by abl solutions GmbH

• Requirements
  • Android
  • iOS
• Release Note
• Installation
• Configure the WifiConnectService
  • initWifiConnectService Options
• wifiConnectService API
  • connectToWifi
  • getLatestLegalTerms
  • legalTermsAccepted
  • legalTermsAcceptedVersion
  • acceptLegalTerms
  • deleteWifiConfiguration
  • isWifiConfigured
  • isConnectedToWifi (iOS)
  • registerOnPermissionRejectedListener
  • unregisterOnPermissionRejectedListener
• Configure the WifiCampaignService
  • initCampaignService Options
• CampaignService API
  • getNextCampaign
• Error handling
• Limitations
  • Android
  • Running on Simulator

Requirements

Android

Required permissions:

• android.permission.INTERNET
• android.permission.CHANGE_WIFI_STATE
• android.permission.ACCESS_WIFI_STATE

Minimum required SDK version: 24 (Android 7 - Nougat)

iOS

Required entitlements (capabilities):

• com.apple.developer.networking.HotspotConfiguration (Hotspot Configuration)
• com.apple.developer.networking.wifi-info (Access WiFi Information)

Minimum required iOS version: 11.0

Release Note

In this version of SDK 0.8.1 - push notifications permission is not required. If you want to use this - use 0.8.0.

For SDK v.0.8.0 User should grant Push notifications permission to be abl connect to Wifi via SDK (e.g. save config for auto-connect). Android <= 12 - not required - it's enabled by default.

Installation

Run

npm install @abl-solutions/wifi-connect

or

yarn add @abl-solutions/wifi-connect

For IOS:

cd ./ios && pod install

Android 13 and higher (For 0.8.0)

You should add this line to your app level manifest file and ask permission for push notifications.

<uses-permission android:id="android.permission.POST_NOTIFICATIONS"/>

Configure the WifiConnectService

initWifiConnectService Options:

Property	required	Type	Description
accessToken	✅	string	An access token that allows access to the WiFi Connect API for the current user.
ignoreNetworkErrorOnSimulator		boolean	Usually, network and WiFi support is limited running on a simulator. Therefore, the WiFi configuration can not be stored on a simulated device. In such a case WifiConnect.connectToWifi() will reject with the error code E_NOT_SUPPORTED_ON_SIMULATOR. If you don't want to reject with this error but instead resolve successfully, set this value to true. Defaults to false.
wifiApiEndpoint		boolean	Optionally set a different REST API endpoint that should be used by this library
isHiddenSSID		boolean	Specifies whether connection represents a hidden network. This value defaults to false if not specified.
android		obejct	Optional Android specific options.
android.timeSpanToWaitForPermissionDialogConfirmationInSeconds		number	This value is only used for connectToWifi on Android 10 devices. This time span is used to wait for granting/declining the permission dialog which is shown by the Operating System. If the user declines the permission dialog within the time span, connectToWifi will reject with the corresponding error code. If the user grants the permissions or the dialog is still opened, connectToWifi will resolve after the time span. This value defaults to 10 seconds if not specified.

import type { WifiConnectService } from '@abl-solutions/wifi-connect';
import { initWifiConnectService } from '@abl-solutions/wifi-connect';

const createWifiConnectService = (accessToken: string): WifiConnectService => {
  return initWifiConnectService({
    accessToken: accessToken,
    android: {
      timeSpanToWaitForPermissionDialogConfirmationInSeconds: 30,
    },
    ignoreNetworkErrorOnSimulator: true,
    isHiddenSSID: true,
    wifiApiEndpoint: 'https://api.wifi.connectivity.abl-solutions.io',
  });
};

wifiConnectService = createWifiConnectService(auth.accessToken);

WifiConnectService API

connectToWifi(deviceId: string, user: User): Promise<void>;

Register this device to get direct access to abl's WiFi networks. The device will be configured to use this WiFi connection. This operation is an asynchrnous process and might take a few seconds to complete. @param deviceId A string that uniquely identifies this device. @param user Details about the user that owns the device. @returns A void promise that resolves if the devices registration was successful and the WiFi configuration is stored in the device settings. Rejects if configuring the WiFi network failed for any reason. Rejects if push notifications permission not granted by user.

Interfaces User

Property	Type	Description
email	string	The e-mail address of the user.
preferredLocale	string	The preferred locale that should be used to interact with the user.

await wifiConnectService.connectToWifi(deviceId, {
  email: email,
  preferredLocale: preferredLocale,
});

getLatestLegalTerms(): Promise<LegalTerms>;

Gets the latest legal terms that must be accepted by the end-user to use the WiFi network. @returns A promise that resolves the legal terms or rejects if loading the legal terms failed.

Interfaces LegalTerms

Property	Type	Description
legalTerms	string	Legal terms content
version	string	Version of legal terms
minimumVersion	string	Minimum legal terms version which must be accepted to access the API.
dateMinLegalTermsActive	string	The date at which the minimal version of legal terms will be enforced.

const terms: LegalTerms = await wifiConnectService.getLatestLegalTerms();

legalTermsAccepted(): Promise<boolean>;

Checks whether the specified user already accepted the legal terms or not. @returns true if the user already accepted the legal terms, otherwise false.

const result: boolean = await wifiConnectService.legalTermsAccepted();

legalTermsAcceptedVersion(): Promise<string>

Checks the version of legal terms accepted by the user. @returns version of the legal terms that was accepted by the user. If the user didn't accepted any legal terms yet - returns 'undefined'

const result: string = await wifiConnectService.legalTermsAcceptedVersion();

acceptLegalTerms(legalTermsVersion: string): Promise<void>;

Accept the specified version of legal terms. This method needs to be called before a user can register to connect to a WiFi network. @param legalTermsVersion The version of the legal terms.

await wifiConnectService.acceptLegalTerms(legalTermsVersion);

deleteWifiConfiguration(deviceId: string): Promise<void>;

Deletes the WiFi settings from the device and unregisters the device from abl servers. Basically, it just reverts the changes that were made by connectToWifi(). @param deviceId A string that uniquely identifies this device.

await wifiConnectService.deleteWifiConfiguration(deviceId);

isWifiConfigured(): Promise<boolean>;

Check if the device is configured to connect to abl's WiFi network. @returns true if the device is configured; otherwise false. In case of error promise will reject with error.

try {
  const result: boolean = await wifiConnectService.isWifiConfigured();
} catch (e) {
  // Do something with an error
}

isConnectedToWifi(): Promise<boolean>; (iOS only)

Check if device is connected to abl's WiFi network. Method should be invoked after connectToWifi() to check connection by received SSID, othervise resolves with false. @returns true if the device is connected; otherwise false. This function works only on iOS devices.

import { Platform } from 'react-native';
if (Platform.OS === 'ios') {
  setTimeout(async () => {
    const result: boolean = await wifiConnectService.isConnectedToWifi();
  }, 4000);
}

registerOnPermissionRejectedListener(callback: () => void): void;

Registers a callback that will be invoked if the required permissions are revoked after connectToWifi fullfilled. This callback can be used to handle the case if a user rejects the permission dialog after the confirmation time span. This callback should be unregistered (using unregisterOnPermissionRejectedListener) after usage to free internal resources. This callback will only be invoked on Android 10 devices. @param callback The callback to invoke.

import { Alert } from 'react-native';
wifiConnectService.registerOnPermissionRejectedListener(() => {
  Alert.alert('Permission rejected', 'Please accept...');
});

unregisterOnPermissionRejectedListener(): void;

Unregister the callback that was previously registered using registerOnPermissionRejectedListener

// return a clean up function to unregister the listener
return () => wifiConnectService?.unregisterOnPermissionRejectedListener();

Configure the WifiCampaignService

initCampaignService Options

Property	required	Type	Description
accessToken	✅	string	An access token that allows access to the Campaign API for the current user.
campaignApiEndpoint		string	Optionally set a different REST API endpoint that should be used by this library.

import type { CampaignService } from '@abl-solutions/wifi-connect';
import { initCampaignService } from '@abl-solutions/wifi-connect';

const createWifiCampaignService = (accessToken: string): CampaignService => {
  return initCampaignService({
    accessToken: accessToken,
    campaignApiEndpoint: process.env.CAMPAIGN_API_ENDPOINT,
  });
};

campaignService = createWifiCampaignService(auth.accessToken);

CampaignService API

getNextCampaign(deviceId: string): Promise<Campaign>;

Campaign

Property	Type	Description
campaignUrl	string	A promise that resolves to a Campaign object if the campaign was fetched successfully. Rejects if fetching the next campaign failed for any reason. The Campaign object contains a flag Campaign.required that will be true if the user needs to watch a campaign. This will be the case if the timespan since watching the last campaign is greater than the configured timespan. If Campaign.required is false then it is not necessary to watch a campaign.
required	boolean	This flag indicating if watching campaign required or not to prolong an access to wifi.
notification	Notification	That's an object that contain title and body that could be string or null

const campaign = await campaignService.getNextCampaign(deviceId);

shouldCloseCampaignView(campaignUrl: string): boolean;

Checking when to close campaign view - campaign at this step considered as watched.

const onNavigationStateChange = (navigationState: { url: string }) => {
  if (campaignService.shouldCloseCampaignView(navigationState?.url)) {
    setCampaign(undefined);
    console.log('campaign viewed - closing webview');
  }
};

Error handling

WifiConnect.connectToWifi(...) and WifiConnect.deleteWifiConfiguration() will reject if configuring the wifi failed for any reason. The error object contains at least the following properties:

{
  "code": "string",
  "message": "string"
}

Additionally, there can be any other properties depending on the error type and platform.

The error code specifies the type of error. The message provides an additional description of the error. Some of these error codes are only specific for a platform.

Error Code	Description	Android	iOS
E_ACTIVITY_DOES_NOT_EXIST	Will be thrown if the React Native context does not include a reference to the current activity.	yes	no
E_INVALID_WIFI_CONFIGURATION	Will be thrown if the WiFi configuration is invalid. This might be a invalid username, password or certificate. If this error occours, this should be reported to abl.	yes	yes
E_USER_REJECTED	The user rejected to connect to the WiFi network.	yes	yes
E_PERMISSION_DENIED	The app is not authorized to configure WiFi networks on the device.	yes	no (iOS will throw E_UNKNOWN_ERROR in this case)
E_FAILED_TO_ENABLE_NETWORK	Android devices can store network configurations that are disabled. This error occours if enabling the network failed. Usually, this should not happen.	yes	no
E_RUNNING_ON_SIMULATOR	Connecting to a WiFi network on simulator is not supported. If you want to ignore this error and get a successful response anyway, set WifiConnectOptions.ignoreNetworkErrorOnSimulator to true.	yes	yes
E_API_ERROR_UNAUTHORIZED	The request failed because the provided access token is invalid, expired or a required scope is missing.	yes	yes
E_API_ERROR_BAD_REQUEST	The request failed because one or more input arguments are missing or invalid.	yes	yes
E_API_ERROR_INTERNAL_SERVER_ERROR	The request failed due to an error on abl servers.	yes	yes
E_API_ERROR	The request failed for any unknown/unexpected reason.	yes	yes
E_UNKNOWN_ERROR	Any other error case that is not described above.	yes	yes

The library provides an enum with all possible error codes.

import { ErrorCode } from '@abl-solutions/wifi-connect';

In all cases where the error message starts with E_API_, the thrown error contains an additional property apiError. This property contains additional information about the error. apiError can be of type string or an object that is JSON serializable.

Limitations

Android

The SDK has the following limitations on Android devices:

• Android 10 and later: If the user rejects the user approval dialog shown by the OS, the permission must be granted manually by the user from the device settings. See Android Developers - Wi-Fi infrastructure - Changing approval status for app. Also see Android Issue Tracker.
• Android 10 only: The user prompt to accept the WiFi configuration will only be visible in the "Android Quick Settings" menu.
• Android 9 and before: No user prompt to accept the WiFi configuration will be shown at all.

Running on Simulator

Simulators do not provide any possibility to simulate a real WiFi connection, because the real WiFi adapter of the host machine can not be used. Therefore, it is not possible to use WifiConnect.connectToWifi() and WifiConnect.deleteWifiConfiguration() in a simulator. Calling this function will raise a E_RUNNING_ON_SIMULATOR error. To overcome this issue in simulators, you can set WifiConnectOptions.ignoreNetworkErrorOnSimulator to true in the init() function. With this option, configuring the WiFi connection will be skipped. But in any case the device will be registered on abl servers. This is handy for testing other features like accepting legal terms or watching campaigns.