What you will learn

This tutorial will teach you how to create your beacon ranging process to detect nearby beacons around a user.

Pre-requisites - What you need to get started

  • A Gitlab Account: The SDK is available through a private Gitlab. You must have received an email with an user account including a link to create a password.
  • Your SDK user information: To initialize the SDK, your should have received a Login, a Password and a Company name.
  • A beacon: A beacon configured on your account is mandatory to test the application.
  • An iOS Device: You need a compatible Bluetooth Low Energy iOS device that is able to detect beacons.
  • The Xcode application: Xcode should be downloaded from the App store

Step 1: Clone the sdk-tutorial repository

  • Clone the sdk-tutorial repository
git clone https://github.com/opsct/sdk-tutorial.git

objectivec:

  • Open the sdk-tutorial>ios>ObjectiveC>Beacon>10-Beacon-Range>Starter folder

SWIFT:

  • Open the sdk-tutorial>ios>SWIFT>Beacon>10-Beacon-Range>Starter folder

Step 2: Configure the SDK

  • Configure your CocoaPod and .plist files

  • Configure the SDK with:

    • the UUID of your beacon
    • the Adtag Platform you would like to connect,
    • and the login, password, and company informations received from Connecthings.

If you need more informations, have a look to the 5 minutes quickstart tutorial.

Step 3: Detect nearby beacons with the beacon range scanning

Now let's add the ATRangeDelegate protocol to our controller, to launch the beacon scanning process.

  • Open the ViewController.h file, and add it to the ATRangeDelegate protocol
@interface ViewController : UIViewController<ATRangeDelegate>
  • Open the ViewController.m file

  • Register the ATRangeDelegate object on the viewDidAppear method

-(void)viewDidAppear:(BOOL)animated{
    [super viewDidAppear:animated];
    [[ATBeaconManager sharedInstance] registerAdtagRangeDelegate:self];
}
  • Unregister the ATRangeDelegate object in the viewDidDisappear method
-(void)viewDidDisappear:(BOOL)animated{
    [super viewDidDisappear:animated];
    [[ATBeaconManager sharedInstance] registerAdtagRangeDelegate:nil];
}
  • Implement the delegate method to launch the scanning process and detect nearby beacons
-(void)didRangeBeacons:(NSArray *)_beacons
		beaconContents:(NSArray *)_beaconContents
	 informationStatus:(ATRangeInformationStatus)informationStatus
			feedStatus:(ATRangeFeedStatus)feedstatus
				region:(CLRegion *)region{
}

Note 1:

  • (NSArray *) _beacons: list of nearby beacons
  • (NSArray *)_beaconContents: list of contents associated to these nearby beacons in Adtag. The content is cached for 10 minutes
  • Region region: the region currently used as a filter
  • ATRangeInformationStatus informationStatus: allows to verify if all the content has been downloaded from Adtag.

The INFORMATION_STATUS values are:

  • ATRangeInformationStatusEmpty: no content has been downloaded yet from the Adtag Platform / the SDK is starting the download
  • ATRangeInformationStatusPartial: content download from Adtag is in progress, and already complete for some of the nearby beacons
  • ATRangeInformationStatusComplete: download is complete for the content of all nearby beacons
  • ATRangeFeedStatus feedStatus: allows to know the status of the connection with the Adtag Platform. The FEED_STATUS values are:
    • ATRangeFeedStatusInProgress: content download from the Adtag Platform is in progress
    • ATRangeFeedStatusBackendError: download error due to Adtag
    • ATRangeFeedStatusNetworkError: content download cannot be completed because the device does not have access to an internet network (wifi or cellular)
    • ATRangeFeedStatusBackendSuccess: successful content download

Note 2:

If the size of the beacons list and of the beaconContents list is different, and if the informationStatus shows ATRangeInformationStatusComplete, then this means that some beacons do not have associated content in Adtag.

Step 4: Display nearby beacons

In order to display the results of the scanning process, the didRangeBeacons method provides the list of nearby beacons, the corresponding Adtag beacon information, and the back-end status.

  • Retrieve the beacons detected around the user with _beacons
  • Retrieve the Adtag beaconContent data associated to the detected beacons
  • Check the feed status range to be informed by beaconContents back end status
-(void)didRangeBeacons:(NSArray *)_beacons beaconContents:(NSArray *)_beaconContents informationStatus:(ATRangeInformationStatus)informationStatus feedStatus:(ATRangeFeedStatus)feedstatus region:(CLRegion *)region{
  
    feedStatusString=@"";
    switch(feedstatus){
        case ATRangeFeedStatusInProgress:
            feedStatusString = @"IN_PROGRESS";
            break;
        case ATRangeFeedStatusBackendError:
            feedStatusString= @"BACKEND_ERROR";
            break;
        case ATRangeFeedStatusNetworkError:
            feedStatusString = @"NETWORK_ERROR";
            break;
        case ATRangeFeedStatusBackendSuccess:
            feedStatusString = @"BACKEND_SUCCESS";
            break;
    }
    
    _txt_nbrBeacon.text =[NSString stringWithFormat:NSLocalizedString(@"beaconArround", @""),feedStatusString,_beacons.count,_beaconContents.count];
}

Step 7: Start testing

  • Connect your iOS Device to your computer (the device must be registered on Appleā€™s developer portal)
  • Activate your beacon
  • In Xcode, click on "Play" to launch the installation process on your phone
  • Once the application is running, wait to see the following message:

"BACKEND_SUCCESS, 1 beacon(s) detected,1 content(s) attached to the beacon(s) on Adtag downloaded"