Native network configuration for iOS apps

Device hot spot network configuration

1. Set the information for the device that you want to configure.
   1. Select a network configuration method.
      Device hot spot network configuration supports network configuration by specifying the ProductKey. You can also start network configuration without specifying a model.

      You can obtain the ProductKey in the following ways.

      • Call a cloud API to obtain the product list or display the product list directly in the app. This API is not provided by the network configuration SDK. After the user makes a selection, determine the ProductKey of the device that you want to configure.
      • Scan the product QR code to obtain the device ProductKey.
   2. Call the `setDevice` method of the SDK to set the configuration information.
2. Start network configuration.
   Set the network configuration method linkType to ForceAliLinkTypeSoftap and call the `startAddDevice` method of the SDK to start network configuration.
3. During network configuration, process the callback information.
   During network configuration, you will receive the `notifyProvisionPrepare` callback. You must then prompt the user to manually switch to the device hot spot. After the switch is complete, call the `toggleProvision` method of the SDK and pass the ssid and password of the currently connected router.
4. Listen for the network configuration result.

   /**
   * Step 1: Set the information for the device to be configured.
   */
   // Method 1: Specify the ProductKey.
   IMLCandDeviceModel *model = [[IMLCandDeviceModel alloc] init];
   model.productKey = @"xxxx"; 
   model.linkType = ForceAliLinkTypeSoftap;
   [kLkAddDevBiz setDevice:model];
   
   // Method 2: Do not specify the model.
   IMLCandDeviceModel *model = [[IMLCandDeviceModel alloc] init];
   model.protocolVersion = @"2.0";
   model.linkType = ForceAliLinkTypeSoftap;
   [kLkAddDevBiz setDevice:model];
   
   // To customize the device hot spot prefix, for example, set the prefix to "demo_".
   model.softApSsidPrefix = @"demo_";
   
   /**
   * Step 2: Start network configuration.
   */
   [kLkAddDevBiz startAddDevice:self];
   
   #pragma mark - Callback methods
   
   - (void)notifyPrecheck:(BOOL)success withError:(NSError *)err
   {
       NSLog(@"notifyPrecheck callback err : %@", err);
   }
   
   /*
    Device hot spot status callback. Prompts are displayed based on the status.
   status: status code. 
   1: Prompt to switch to the device hot spot. 
   2: Switched to the device hot spot. 
   3: Data sent (dic contains "token"). 
   4: Prompt to switch back to the router. 
   5: Switched back to the router.
   */
   - (void)notifyProvisioningNoticeForSoftAp:(int)status withInfo:(NSDictionary *)dic
   {
       NSLog(@"notifyProvisioningNoticeForSoftAp,%d,%@",status,dic);
   }
   
   - (void)notifyProvisionPrepare:(LKPUserGuideCode)guideCode
   {
       NSLog(@"notifyProvisionPrepare callback guide code : %ld", guideCode);
       if(guideCode == LKPGuideCodeWithUserGuideForSoftAp){
           /**
           * Step 3: Prompt the user to switch to the device hot spot. After the switch is complete, call toggleProvision. For more information, see inputSsidAndPassword.
           */
       }
   }
   
   - (void)inputSsidAndPassword
   {
       NSString *ssid = @"example ssid";
       NSString *password = @"1qaz@WSX";
       NSInteger timeout = 60; // Unit: seconds (s)
       [kLkAddDevBiz toggleProvision:ssid pwd:password timeout:timeout];
   }
   
   -(void)notifyProvisioning 
   {
       NSLog(@"notifyProvisioning callback (Network configuration in progress...) ");
   }
   
   /**
   * Step 4: Listen for the result callback.
   */
   - (void)notifyProvisionResult:(IMLCandDeviceModel *)candDeviceModel withProvisionError:(NSError *)provisionError
   {
       NSLog(@"Network configuration result: %@",candDeviceModel);
   }

Bluetooth-assisted network configuration

1. Check the network configuration SDK version.
   Ensure that the network configuration SDK version in the Podfile dependency is 1.11.5 or later and that the Bluetooth SDK is integrated.

     # Network configuration SDK dependency
     pod 'IMSDeviceCenter', '1.11.5'
   
     # Bluetooth SDK dependency
     pod 'IMSBreezeSDK', '1.6.9'

2. Set the information for the device that you want to configure.
   1. Obtain and set the ProductKey and productID of the device that you want to configure.
      You can obtain the information in the following ways.

      • Call the `IMLLocalDeviceMgr` local discovery API of the SDK to search for nearby Bluetooth-assisted network configuration devices and obtain their information.
      • Call a cloud API to obtain the product list or display the product list directly in the app. This API is not provided by the network configuration SDK. After the user makes a selection, determine the ProductKey and productID of the device that you want to configure.
      • Scan the QR code to obtain the information of the device that you want to configure, including the ProductKey and productID.
   2. Call the `setDevice` method of the SDK to set the configuration information.
3. Start network configuration.
   Set the network configuration method linkType to ForceAliLinkTypeBLE and call the `startAddDevice` method of the SDK to start network configuration.
4. During network configuration, process the callback information.
   During network configuration, you will receive the `notifyProvisionPrepare` callback. You must then prompt the user to manually switch to the device hot spot. After the switch is complete, call the `toggleProvision` method of the SDK and pass the ssid and password of the currently connected router.
5. Listen for the network configuration result.
   The following code provides an example.

   /**
   * Step 1: Set the information for the device to be configured.
   */
   // Method 1: Get information through local discovery.
   [[IMLLocalDeviceMgr sharedMgr] startDiscovery:^(NSArray *devices, NSError *err) {
           // devices is an array of IMLCandDeviceModel objects.
           // You can distinguish the network type of the device to be configured based on devType in IMLCandDeviceModel:
           // devType @"ble_subtype_2" indicates a Bluetooth-assisted network configuration device. */
   
         // Filter to get the required Bluetooth-assisted device data productId. You can use the productId to query the productKey through the thing/productInfo/queryProductKey API.
   
           IMLCandDeviceModel *model = [[IMLCandDeviceModel alloc] init];
           model.productKey = @"xxxx"; 
           model.productId = @"xxxx"; 
           model.linkType = ForceAliLinkTypeBLE;
           [kLkAddDevBiz setDevice:model];
       }];
   
   // Method 2: Set information using other methods.
   IMLCandDeviceModel *model = [[IMLCandDeviceModel alloc] init];
   model.productKey = @"xxxx"; 
   model.productId = @"xxxx"; 
   model.linkType = ForceAliLinkTypeBLE;
   [kLkAddDevBiz setDevice:model];
   
   
   /**
   * Step 2: Start network configuration.
   */
   [kLkAddDevBiz startAddDevice:self];
   
   #pragma mark - Callback methods
   
   - (void)notifyPrecheck:(BOOL)success withError:(NSError *)err
   {
       NSLog(@"notifyPrecheck callback err : %@", err);
   }
   
   - (void)notifyProvisionPrepare:(LKPUserGuideCode)guideCode
   {
       NSLog(@"notifyProvisionPrepare callback guide code : %ld", guideCode);
       if(guideCode == LKPGuideCodeOnlyInputPwd){
           /**
           * Step 3: Pass the Wi-Fi information during network configuration.
           */
           NSString *ssid = @"example ssid";
           NSString *password = @"example pwd";
           NSInteger timeout = 60; // Unit: seconds (s)
           [kLkAddDevBiz toggleProvision:ssid pwd:password timeout:timeout];
       }
   }
   -(void)notifyProvisioning 
   {
       NSLog(@"notifyProvisioning callback (Network configuration in progress...) ");
   }
   
   /**
   * Step 4: Listen for the result callback.
   */
   - (void)notifyProvisionResult:(IMLCandDeviceModel *)candDeviceModel withProvisionError:(NSError *)provisionError
   {
       NSLog(@"Network configuration result: %@",candDeviceModel);
   }

One-click network configuration

1. Set the information for the device that you want to configure.
   1. Obtain and set the ProductKey of the device that you want to configure.
      You can obtain the information in the following ways.

      • Call a cloud API to obtain the product list or display the product list directly in the app. This API is not provided by the network configuration SDK. After the user makes a selection, determine the ProductKey and productID of the device that you want to configure.
      • Scan the QR code to obtain the device ProductKey.
   2. Call the `setDevice` method of the SDK to set the configuration information.
2. Start network configuration.
   Set the network configuration method linkType to ForceAliLinkTypeBroadcast and call the `startAddDevice` method of the SDK to start network configuration.
3. During network configuration, process the callback information.
   During network configuration, you will receive the `notifyProvisionPrepare` callback. You must then prompt the user to manually switch to the device hot spot. After the switch is complete, call the `toggleProvision` method of the SDK and pass the ssid and password of the currently connected router.
4. Listen for the network configuration result.
   The following code provides an example.

   /**
   * Step 1: Set the information for the device to be configured.
   */
   IMLCandDeviceModel *model = [[IMLCandDeviceModel alloc] init];
   model.productKey = @"xxx"; 
   model.linkType = ForceAliLinkTypeBroadcast;
   [kLkAddDevBiz setDevice:model];
   
   /**
   * Step 2: Start network configuration.
   * Set the configuration information and start network configuration.
   */
   [kLkAddDevBiz startAddDevice:self];
   
   #pragma mark - Callback methods
   
   - (void)notifyPrecheck:(BOOL)success withError:(NSError *)err
   {
       NSLog(@"notifyPrecheck callback err : %@", err);
   }
   
   - (void)notifyProvisionPrepare:(LKPUserGuideCode)guideCode
   {
       NSLog(@"notifyProvisionPrepare callback guide code : %ld", guideCode);
       if(guideCode == LKPGuideCodeOnlyInputPwd){
           /**
           * Step 3: Pass the Wi-Fi information during network configuration.
           */
           NSString *ssid = @"example ssid";
           NSString *password = @"example pwd";
           NSInteger timeout = 60; // Unit: seconds (s)
           [kLkAddDevBiz toggleProvision:ssid pwd:password timeout:timeout];
       }
   }
   -(void)notifyProvisioning 
   {
       NSLog(@"notifyProvisioning callback (Network configuration in progress...) ");
   }
   
   /**
   * Step 4: Listen for the result callback.
   */
   - (void)notifyProvisionResult:(IMLCandDeviceModel *)candDeviceModel withProvisionError:(NSError *)provisionError
   {
       NSLog(@"Network configuration result: %@",candDeviceModel);
   }

Zero-configuration networking

1. Set the information for the device that you want to configure.
   1. Obtain and set the information for the device that you want to configure.
      To obtain the information, call the `IMLLocalDeviceMgr` local discovery API of the SDK to search for nearby zero-configuration networking devices.
   2. Call the `setDevice` method of the SDK to set the configuration information.
2. Start network configuration.
   Call the `startAddDevice` method of the SDK to start network configuration.
3. During network configuration, process the callback information.
   During network configuration, you will receive the `notifyProvisionPrepare` callback. You must then prompt the user to manually switch to the device hot spot. After the switch is complete, call the `toggleProvision` method of the SDK and pass the ssid and password of the currently connected router.
4. Listen for the network configuration result.
   The following code provides an example.

   
   /**
   * Step 1: Set the information for the device to be configured.
   */
   [[IMLLocalDeviceMgr sharedMgr] startDiscovery:^(NSArray *devices, NSError *err) {
           // devices is an array of IMLCandDeviceModel objects.
           // You can filter for the zero-configuration networking device information model where addDeviceFrom in IMLCandDeviceModel is "ZERO_DEVICE".
           [kLkAddDevBiz setDevice:model];
       }];
   
   
   /**
   * Step 2: Start network configuration.
   * Set the configuration information and start network configuration.
   */
   [kLkAddDevBiz startAddDevice:self];
   
   #pragma mark - Callback methods
   
   - (void)notifyPrecheck:(BOOL)success withError:(NSError *)err
   {
       NSLog(@"notifyPrecheck callback err : %@", err);
   }
   
   -(void)notifyProvisioning 
   {
       NSLog(@"notifyProvisioning callback (Network configuration in progress...) ");
   }
   
   /**
   * Step 4: Listen for the result callback.
   */
   - (void)notifyProvisionResult:(IMLCandDeviceModel *)candDeviceModel withProvisionError:(NSError *)provisionError
   {
       NSLog(@"Network configuration result: %@",candDeviceModel);
   }

Device attachment

This SDK provides an API to obtain an attachment token. The attachment API is not provided by this SDK.