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

  • Your SDK credentials, including an SDK Login, Password, and Company Key to initialize the SDK.
  • A BLE beacon, which has been configured on your account, in order to test interactions with your app.
  • An iOS Device, with Bluetooth 4.0 and iOs 8 and above.
  • The Xcode application, which you can download 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>8-Beacon-Range>Starter folder

SWIFT:

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

Step 2: Configure the SDK

  • Configure your CocoaPod files and .plist
  • Configure your SDK with:
    • the UUID of your beacon
    • the appropriate Adtag Environment (DEMO / PREPROD / PROD / PROD_US)
    • your SDK credentials

Switch to Swift

[[[ATAdtagInitializer sharedInstance] configureUrlType:ATUrlTypeProd
                                              andLogin:@"__USER__" 
                                           andPassword:@"__PSWD__" 
                                            andCompany:@"__COMPANY__"] 
                                           synchronize];
ATAdtagInitializer.sharedInstance().configureUrlType(__UrlType__, 
                                            andLogin: "__USER__", 
                                         andPassword: "__PSWD__", 
                                          andCompany: "__COMPANY__")
                                   .synchronize();

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

Switch to Swift

@interface ViewController : UIViewController<ATRangeDelegate>
class ViewController: UIViewController, ATRangeDelegate {
  • Open the ViewController.m file
  • Register the ATRangeDelegate object on the viewDidAppear method

Switch to Swift

-(void)viewDidAppear:(BOOL)animated{
    [super viewDidAppear:animated];
    [[ATBeaconManager sharedInstance] registerAdtagRangeDelegate:self];
}
override func viewDidAppear(_ animated: Bool) {
    super.viewDidAppear(animated);
    ATBeaconManager.sharedInstance().registerAdtagRangeDelegate(self);
}
  • Unregister the ATRangeDelegate object in the viewDidDisappear method

Switch to Swift

-(void)viewDidDisappear:(BOOL)animated{
    [super viewDidDisappear:animated];
    [[ATBeaconManager sharedInstance] registerAdtagRangeDelegate:nil];
}
override func viewDidDisappear(_ animated: Bool) {
    super.viewDidAppear(animated);
    ATBeaconManager.sharedInstance().registerAdtagRangeDelegate(nil);
}
  • Implement the delegate method to launch the scanning process and detect nearby beacons

Switch to Swift

-(void)didRangeBeacons:(NSArray *)_beacons
		beaconContents:(NSArray *)_beaconContents
	 informationStatus:(ATRangeInformationStatus)informationStatus
			feedStatus:(ATRangeFeedStatus)feedstatus{
}
func didRangeBeacons(_ _beacons: [Any]!, beaconContents: [Any]!, informationStatus: ATRangeInformationStatus, feedStatus: ATRangeFeedStatus) {
}

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
  • 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

Switch to Swift

-(void)didRangeBeacons:(NSArray *)_beacons beaconContents:(NSArray *)_beaconContents informationStatus:(ATRangeInformationStatus)informationStatus feedStatus:(ATRangeFeedStatus)feedstatus{
    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(@"beaconAround", @""),feedStatusString,_beacons.count,_beaconContents.count];
}
func didRangeBeacons(_ _beacons: [Any]!, beaconContents: [Any]!, informationStatus: ATRangeInformationStatus, feedStatus: ATRangeFeedStatus) {
    var feedStatusString: String
    switch feedStatus {
        case ATRangeFeedStatusInProgress:
            feedStatusString = "IN_PROGRESS"
        case ATRangeFeedStatusBackendError:
            feedStatusString = "BACKEND_ERROR"
        case ATRangeFeedStatusNetworkError:
            feedStatusString = "NETWORK_ERROR"
        case ATRangeFeedStatusBackendSuccess:
            feedStatusString = "BACKEND_SUCCESS"
        default:
            feedStatusString = ""
    }
    self.txt_nbrBeacon.text = String(format: NSLocalizedString("beaconDetected", comment: ""), 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"