What you will learn

You will learn:

  • to configure your Podfile with our Gitlab and our SDK
  • to configure the SDK in your application

Prerequisites - What you need to get started

  • Your SDK credentials: including an SDK Login, Password, and Company Key to initialize the SDK.
  • A QR Code and an NFC Tag: you need a QR CODE and an NFC Tag set up on your Herow Account to test the application
  • An iOS Device: with iOs 9 and above for QR CODE and iOs 11 and above for NFC.
  • 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/Connecthings/sdk-tutorial.git

objectivec

  • In the cloned sdk-tutorial folder, navigate to ios>ObjectiveC>QrNfc>Starter

SWIFT

  • In the cloned sdk-tutorial folder, navigate to ios>SWIFT>QrNfc>Starter
  • Install CocoaPods $gem install cocoapods
  • Create a Podfile. This can be done by running $touch Podfile and add your dependencies
source 'https://github.com/CocoaPods/Specs.git'
source 'https://forge.herow.io/pub/Specs'
platform :ios, '9.0'

target 'QrNfcV3' do
    # Uncomment this line if you're using Swift or would like to use dynamic frameworks
    use_frameworks!
    swift_version = "4.0"
    pod "HerowScanProximity", '~> 4.0.1'

    post_install do |installer|
        installer.pods_project.targets.each do |target|
            target.build_configurations.each do |config|
                config.build_settings['SWIFT_VERSION'] = '4.0'
            end
        end
    end

end

Check out the Cocoapods site for more information

  • Run $pod update in your project directory.
  • Open App.xcworkspace that was created.

Step 3: Setup the permissions

Setup the permission to use the camera

  • Open the info.plist file and the following permission
<key>NSCameraUsageDescription</key>
<string>Your text to describe the usage</string>

Setup the permissions to use the NFC

Enable the NFC Tag service

  • Connect to your developper apple account
  • Go to the App Ids section
  • Select the App Id associated to your application or create one, if you don't already get one
  • Enable the NFC Tag reading service

Activate the NFC Tag Reading capability

  • Go to your application target
  • Select the capabilities item
  • Enable the Near Field Communication Tag Reading capability

Add the permission to use the NFC

  • In Xcode, Open the info.plist file and the following permission
<key>NFCReaderUsageDescription</key>
<string>your NFC tag</string>

Setup the supported NFC content formats

  • The previous steps must have conduct to the automatic creation of an .entitlements file in your Xcode project
  • Open it and add the following lines:
<key>com.apple.developer.nfc.readersession.formats</key>
<array>
    <string>NDEF</string>
</array>

Step 4: Configure the HerowInitializer

  • Open the AppDelegate class.

  • Import the HerowConnection library

Switch to Swift

@import HerowConnection;
import HerowConnection
  • Configure the HerowInitializer with the received information from Connecthings:

Switch to Swift

[[[[HerowInitializer shared] configPlatform: HerowPlatform.prod]
                                     configUserWithLogin:@"your username"
                                     password:@"your password"
                                     company:@"your company"]
                                     synchronize];
HerowInitializer.shared.configPlatform(Platform.prod)
                 .configUser(login: "your username", password: "your password", company: "your company")
                 .synchronize()

Note:

The HerowInitializer allows to configure the access to the various Herow platforms.

Connecthings gives you access to three platforms :

  • The Demo platform is ideal for the technical Proof of Concept (POC) phase
  • The Pre-production platform is ideal for the beta versions
  • The Production platform is used when you're ready to publish your application

Warning:

Connecthings sent you two different access keys for each platform:

  • An access key to sign in the Herow Platform
  • An access key to use with the mobile SDK, called API_KEY.

Be sure to use the correct API KEY (login, password, and platform) to connect the SDK to the Herow Platform, otherwise the application won't detect the beacons.

Step 5: Configure the QR CODE Tag reading

  • Open the ViewController.h

  • Import the HerowConnection, HerowScanProximity, and ConnectPlaceCommon libraries

Switch to Swift

@import HerowConnection;
@import HerowScanProximity;
@import ConnectPlaceCommon;
import HerowConnection
import HerowScanProximity
import ConnectPlaceCommon
  • Declare an HerowScanProximityManager and an HerowQrCodeReader parameter

Switch to Swift

@implementation ViewController {
    HerowScanProximityManager *herowScanProximityManager;
    HerowQrCodeReader *qrCodeReader;
}

- (void)viewDidLoad {
    [super viewDidLoad];
    herowScanProximityManager = [HerowScanProximityManager shared];
    qrCodeReader = [[HerowQrCodeReader alloc] initWithController:self cancelLabel:@"Cancel"];
}
    var herowScanProximityManager: HerowScanProximityManager
    var qrCodeReader: HerowQrCodeReader?

    override func viewDidLoad() {
        super.viewDidLoad()
        herowScanProximityManager = HerowScanProximityManager.shared
        qrCodeReader = HerowQrCodeReader(controller: self, cancelLabel: "Cancel")
    }

Note:

The SDK is using the QRCodeReader.swift framework.

The SDK offers you the possibility to easily customize the cancel label, when initializing the HerowQrCodeReader.

You can access the QRCodeReaderViewController, using swift HerowQrCodeReader.readerVc, which offers you more options to customize the view.

Refer to the QRCodeReader.swift framework documentation to learn more about customizing this view.

  • Hide the Qr Code button if the camera permission has been denied - or display a specific message or icon showing that the functionality is not available.

Switch to Swift

- (void)viewDidLoad {
    [super viewDidLoad];
    [...]
    [_btnQrCode setHidden:[qrCodeReader isCameraAccessDenied]];
}
override func viewDidLoad() {
    super.viewDidLoad()
    [...]
    btnQrCode.isHidden = qrCodeReader!.isCameraAccessDenied()
}
  • Launch the Qr Code Reader when the user clicks on a button:

Switch to Swift

- (IBAction) openQrCodeReader:(id)sender {
    [qrCodeReader start];
}
@IBAction func openQrCodeReader(_ sender: Any) {
    qrCodeReader?.start()
}

Note:

The start method automatically requests permission to use the camera if the permission has never been asked before.

Step 6: Configure the NFC Tag reading

  • Open the ViewController
  • Initialize the HerowNfcReader in the viewDidLoad method

Switch to Swift

@implementation ViewController {
    [...]
    HerowNfcReader *nfcReader;
}

- (void)viewDidLoad {
    [super viewDidLoad];
    [...]
    nfcReader = [[HerowNfcReader alloc] initWithMessage:@"Read NFC TAG"];
}
  var nfcReader: HerowNfcReader?

    override func viewDidLoad() {
        super.viewDidLoad()
        [...]
        nfcReader = HerowNfcReader(message: "Read NFC TAG")
    }

Note:

The field “message” in the HerowNfcReader constructor, is meant to provide explanation for scanning the NFC tag and will be shown at the bottom of the NFC view.

  • Hide the NFC button if the NFC is not supported by the os version or the Device, using the isReadingNfcTagSupported method from the NfcUtils class.

Switch to Swift

- (void)viewDidLoad {
    [super viewDidLoad];
    [...]
    [_btnNfc setHidden:![NfcUtils isReadingNfcTagSupported]];
}
  override func viewDidLoad() {
        super.viewDidLoad()
        [...]
        btnNfcReader.isHidden = !NfcUtils.isReadingNfcTagSupported()
    }
  • Launch the tag reader when the user clicks on a button:

Switch to Swift

- (IBAction) openNfcReader:(id)sender {
    [nfcReader start];
}
@IBAction func openNfcReader(_ sender: Any) {
    nfcReader?.start()
}

Note:

Another possibility is to launch the TAG Reading as soon as the controller loads.

Step 7: Receive the content from the Herow platforms

  • Open the ViewController

  • Implement the HerowScanProximityDelegate in the ViewController which allows to receive the HerowPlaceInAppAction when the QR CODE or NFC tag is flashed:

Switch to Swift

- (void)onScanProximityContentDownloadInProgress {
    _textViewContent.text = @"Download in progress";
}

- (void)onScanProximityContentWithPlaceInAppAction:(HerowPlaceInAppAction *)placeInAppAction {
  if (placeInAppAction == nil) {
      _textViewContent.text = @"No content found associated to the tag";
  } else {
      _textViewContent.text = [[placeInAppAction herowContent] getValueWithCategoryName:@"Name" fieldName:@"Nom"];
  }
}
func onScanProximityContentDownloadInProgress() {
    tvContentError.text = "Waiting for content result..."
}

func onScanProximityContent(placeInAppAction: HerowPlaceInAppAction?) {
  if let placeInAppAction = placeInAppAction {
       tvContentError.text = "\(placeInAppAction.herowContent!.getValue(categoryName: "Name", fieldName: "Nom"))\n\(placeInAppAction.getDescription())"
   } else {
       tvContentError.text = "No content associated to the tag"
   }
}

Note:

The HerowScanProximityDelegate gets two methods:

  • onScanProximityContentDownloadInProgress: To be notified when the download of a content from Herow starts.
  • onScanProximityContent(HerowPlaceInAppAction): To be notified when the download of a content is finished

Warning:

In the onScanProximityContent, the HerowPlaceInAppAction can be null in case of error.

  • Register the viewController as a HerowScanProximityDelegate to the HerowScanProximityManager in the viewWillAppear method:

Switch to Swift

- (void)viewWillAppear:(BOOL)animated {
    herowScanProximityManager.scanProximityDelegate = self;
    [super viewWillAppear:animated];
}
  override func viewWillAppear(_ animated: Bool) {
        herowScanProximityManager?.scanProximityDelegate = self
        super.viewWillAppear(animated)
    }
  • Unregister the viewController from the HerowScanProximityManager in the viewWillDisappear method:

Switch to Swift

- (void)viewWillDisappear:(BOOL)animated{
    herowScanProximityManager.scanProximityDelegate = nil;
    [super viewWillDisappear:animated];
}
override func viewWillDisappear(_ animated: Bool) {
    herowScanProximityManager.scanProximityDelegate = nil
    super.viewWillDisappear(animated)
}

Step 8: Be notified about errors

  • Open the ViewController
  • Implement the ProximityHealthCheckDelegate in the ViewController

Switch to Swift

- (void) onProximityHealthCheckUpdate:(HealthStatus *)healthStatus {
    NSMutableString *errorMsg = [[NSMutableString alloc] initWithString:@""];
    NSSet *typesToCheck = [NSSet setWithObjects:@1, @2, @3, @4, @5, @6, nil];
    if ([healthStatus isDown]) {
        for (ServiceStatus *serviceStatus in healthStatus.serviceStatusMap.allValues) {
            if ([serviceStatus isDown] &&
            ([typesToCheck member:[NSNumber numberWithInteger:serviceStatus.type]] != nil)) {
                for (Status *status in serviceStatus.statusList) {
                    [errorMsg appendString:status.message];
                    [errorMsg appendString:@"\n"];
                }
            }
        }
    }
    _textViewContent.text = errorMsg;
}
func onProximityHealthCheckUpdate(_ healthStatus: HealthStatus) {
    var errorMsg: String = ""
    let typesToCheck = [1, 2, 3, 4, 5, 6]
    if healthStatus.isDown {
        for serviceStatus in healthStatus.serviceStatusMap.values {
            if serviceStatus.isDown(), typesToCheck.contains(Int(serviceStatus.type)) {
                for status in serviceStatus.statusList {
                    errorMsg += status.message as String + "\n"
                }
            }
        }
    }
    tvContentError.text = errorMsg
}```

* Declare an **HerowInitializer** parameter

Switch to Swift
<!--{.btn-switch.swift}-->

```objectivec
@implementation ViewController {
    HerowInitializer *herowInitializer;
    [...]
}

- (void)viewDidLoad {
    [super viewDidLoad];
    [...]
    herowInitializer = [HerowInitializer shared];
}
    var herowInitializer: HerowInitializer

    override func viewDidLoad() {
        super.viewDidLoad()
        [...]
        herowInitializer = HerowInitializer.shared
    }
  • Register the viewController as a ProximityHealthCheckDelegate to the HerowInitializer in the viewWillAppear method:

Switch to Swift

- (void)viewWillAppear:(BOOL)animated {
    [...]
    [herowInitializer registerProximityHealthCheckDelegate:self];
    [super viewWillAppear:animated];
}
override func viewWillAppear(_ animated: Bool) {
    [...]
    herowInitializer?.registerProximityHealthCheckDelegate(self)
    super.viewWillAppear(animated)
}
  • Unregister the viewController from the HerowInitializera in the viewWillDisappear method:

Switch to Swift

- (void)viewWillDisappear:(BOOL)animated{
    [super viewWillDisappear:animated];
    [...]
    [herowInitializer unregisterProximityHealthCheckDelegate:self];
}
override func viewWillDisappear(_ animated: Bool) {
    [...]
    herowInitializer?.unregisterProximityHealthCheckDelegate(self)
    super.viewWillDisappear(animated)
}

Step 9: Test your configuration

  • Connect your iOS Device to your computer
  • Into Xcode, click on "Play" to launch the installation on your phone
  • Flash the QR Code or the Nfc Tag received from Connecthings
  • The name of the point associated to the QR Code/Nfc Tag is displayed