Working with NEHotspotHelper

I had to evaluate NEHotspotHelper for a project I am working on. The documentation from Apple is sordid to say the least. Here are a few bits and pieces of information that will help you understand the API better.

Apply for the Network Extension Entitlement

You may already know this but to use the NEHotspotHelper API you will need to apply for the Network Extension Entitlement from Apple. It may take several days for Apple to approve or reject your application.

Modify your Provisioning Profiles

Once you are granted the entitlement, go to iOS developer console and add the entitlement to your developer and deployment provisioning profiles. Many on the Internet will tell you to create a new set of provisioning profiles. That is not necessary. You can add entitlements to existing profiles. Download these modified profiles and re-install them on your development machine.

Add Background Mode

In our case we wanted to use the Wi-Fi Hotspot Authentication API of NEHotspotHelper. This requires the app to run in the background mode. Edit your Info.plist file and add the network-authentication background mode.

Use the Wi-Fi Hotspot Authentication API

The purpose of the authentication API is to implement custom application level logic to authenticate the connection to a WIFI hotspot. This authentication is a two step process:

  1. First connect to the hotspot providing the hotspot’s password.
  2. Then perform custom authentication. For example, this can involve communicating with a server and passing additional credentials.

This process uses a callback based approach. The first thing you do is register a closure or lambda that is invoked at various times with a command object.

let options: [String: NSObject] = [kNEHotspotHelperOptionDisplayName : "Join this WIFI" as NSObject]
let queue: DispatchQueue = DispatchQueue(label: "com.mobiarch", attributes: DispatchQueue.Attributes.concurrent)

NSLog("Started wifi scanning.")

NEHotspotHelper.register(options: options, queue: queue) { (cmd: NEHotspotHelperCommand) in
  NSLog("Received command: \(cmd.commandType.rawValue)")
}

There are three command types that you need to be aware of to perform custom authentication.

  • NEHotspotHelperCommandType.filterScanList – iOS will call your closure with this command type when the user opens the WIFI Settings page. You can obtain a list of all available hotspots from the command. Your code needs to create a filtered list of hotspots that you will like to authenticate with. You also need to set the WIFI password for these hotspots at this point. Once the closure returns, iOS will show the display name below the filtered hotspots. The display name is set using the kNEHotspotHelperOptionDisplayName option as shown in the code above. Note: Filtering does not really remove other hotspots from the list in the WIFI settings page. It is simply meant to identify the networks that your app deems appropriate for authentication.
  • NEHotspotHelperCommandType.evaluate – If the user taps on one of your filtered hotspots and makes a connection the closure is called again with an evaluate command. You can perform custom business logic to evaluate the connected hotspot. If it is appropriate, your code should set a high confidence level for the network.
  • NEHotspotHelperCommandType.authenticate – After the evaluation phase the closure is called again with an authenticate command. Your code can now perform custom authentication logic and respond with a success or failure status. If successful the connection is finally established.

Remember, your callback closure will only be called if the user opens the WIFI Settings page. Also, the user must manually initiate a connection to a hotspot. Your code can not automatically connect.

A sample code for the lambda can look like this.

{ (cmd: NEHotspotHelperCommand) in
    NSLog("Received command: \(cmd.commandType.rawValue)")
    
    if cmd.commandType == NEHotspotHelperCommandType.filterScanList {
        //Get all available hotspots
        var list: [NEHotspotNetwork] = cmd.networkList! 
        //Figure out the hotspot you wish to connect to
        let desiredNetwork : NEHotspotNetwork? = getBestScanResult(list) 

        if let network = desiredNetwork {
            network.setPassword("password") //Set the WIFI password

            let response = cmd.createResponse(NEHotspotHelperResult.success)

            response.setNetworkList([network])
            response.deliver() //Respond back with the filtered list
        }
    } else if cmd.commandType == NEHotspotHelperCommandType.evaluate {
        if let network = cmd.network {
            //Set high confidence for the network
            network.setConfidence(NEHotspotHelperConfidence.high) 

            let response = cmd.createResponse(NEHotspotHelperResult.success)
            response.setNetwork(network)
            response.deliver() //Respond back
        }
    } else if cmd.commandType == NEHotspotHelperCommandType.authenticate {
        //Perform custom authentication and respond back with success
        // if all is OK
        let response = cmd.createResponse(NEHotspotHelperResult.success)
        response.deliver() //Respond back
    }
}

For additional details about the different command types, see the official document.

Advertisements

15 thoughts on “Working with NEHotspotHelper

  1. Did you have to add the com.apple.developer.networking.HotspotHelper manually to the entitelement file?
    I received the networkextension entitelement from apple, add this property to the entitelement file, but somehow my registered helper never get called

    • Hi, I am not sure what an “entitlement file” is. From my experience when you are granted an entitlement, you need to add it to your development provisioning profile (using iOS developer web site). You need to then download the provisioning profile and install it in your developer machine.

  2. Sorry, I’m not sure if I understand: the NEHotspotHelper could make possible if you want to automatically join to a specific WLAN (like the wifi of your store).

      • But, if the user enter in the range of you hotspot, you can show any alert or something to invite for join? Like ‘Hey, do you want to access internet with our wifi?’

      • As I have said in my post: “Remember, your callback closure will only be called if the user opens the WIFI Settings page. Also, the user must manually initiate a connection to a hotspot. Your code can not automatically connect.”

        So, technically once the user opens the WIFI settings page and your callback gets called you can post a notification asking the user to join a hotspot.

  3. At the Authentication point,
    //Perform custom authentication and respond back with success
    // if all is OK

    I am unable to make any webrequests, do you perhaps know how to get around this?
    Only after I have delivered the result, there is a small window (300ms ~ 500ms) where I am able to do web calls but then the code pauses after that.

    • Deliver the result after you have made the web call and not before. The result should contain a success or failure flag as shown in the example code. Presumably the web call will tell you what that flag should be.

      • I understand. Try making a synchronous web call. So that the web call will block until the response comes back. Then deliver the result. As a proof of concept try replacing the web call with a blocking sleep call and wait for say 5 seconds.

        NSThread.sleepForTimeInterval(5)
        //…
        response.deliver()

        Your app should not get terminated while it is waiting. If this works then replace the sleep with a blocking web call.

      • Thank you Bibhas2. I have managed to get it working before delivering the response. Basically the gateway has a local domain name and an IP address (Default Gateway IP) – So I made a web request to the default ip instead of the domain name, and it works perfect now. After I authenticate the user on the gateway, I deliver the response.

  4. Hi,
    Do I need to create any specific iOS Extension to use NEHotspotHelper?. It would be great if you could guide me with the project creation process. I was going through the developer site, but there are hardly any references.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s