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

  • A Gitlab Account: The SDK is available through a private Gitlab. You must have received an email from our private Gitlab that permits you to create an account associated to your email.
  • Your SDK user information: To initialize the SDK, your should have received a User, 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: Configure your access to our Gitlab

  • Generate your SSH KEY. You can check the how to Generate SSH tutorial
  • Connect to the Connecthing Gitlab server
  • Click on profile settings at the left of the page and they will populate to box automatically.
  • Click on SSH keys, then, at the top of the page, add your SSH KEY as describe in the picture bellow

Note:

If you forget the your Gitlab password, you can reset it here

Step 2: Clone the beacon-tutorial repository

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

objectivec

  • Open the iOs>ObjectiveC>Beacon>1-QuickStart>QuickStart-starter folder from the cloned sdk-tutorial folder

SWIFT

  • Open the iOs>SWIFT>Beacon>1-QuickStart>QuickStart-starter folder from the cloned sdk-tutorial folder
  • Install CocoaPods $ gem install cocoapods
  • At the root of the sample repository, check if a Podfile already exists
  • If the file doesn't exist in your project repository create it. This can be done by running
    $ touch Podfile
  • Add the following parameters to your Podfile
platform :ios, '8.0'

target 'QuickComplete' do
  # Uncomment this line if you're using Swift or would like to use dynamic frameworks
  use_frameworks!
  pod "ATConnectionHttp",:git => "https://forge.adtag.eu/ConnecthingsSDK/ATConnectionHttp.git", :tag => "2.4.1"
  pod "ATAnalytics",:git => "https://forge.adtag.eu/ConnecthingsSDK/ATAnalytics.git", :tag => "2.4.1"
  pod "ATLocationBeacon",:git => "https://forge.adtag.eu/ConnecthingsSDK/ATLocationBeacon.git", :tag => "2.4.1"
  # Pods for QuickComplete

  target 'QuickCompleteTests' do
    inherit! :search_paths
    # Pods for testing
  end

  target 'QuickCompleteUITests' do
    inherit! :search_paths
    # Pods for testing
  end
end

  • Run $ pod install in your project directory

Note:

Your project is Linked to Corelocation, and libsqlite3 Frameworks

Step 4: Launch our sample into Xcode

  • Open App.xcworkspace: you will use this new file generated to manage your project.
  • Click in your target project, then "build settings". Make sure that Allow Non-modular includes in Frameworks Modules is set to yes as describe in the picture bellow

Step 5 : Configure .plist file in Xcode

  • Open .plist file. Add the following keys to your Info.plist file:

Requesting Permission Privacy Settings.

The SKD use the CBCentralManager API, to ask the use permission before access the user Bluetooth private data you should add the following bluetooth usage description

<key>Privacy - Bluetooth Peripheral Usage Description</key>
<string>Your message goes here</string>

Note: If your app (including access to this data by all third party libraries used in your app) attempts to access privacy-sensitive data without a usage description, your app will exit. Additionally, App Review checks for use of privacy-sensitive data, and rejects apps >that request access to this data without a usage description.

The SKD ask the use permission before access the user Location private data Specifies the reason for your app to access the user’s location information. you should add the following location description

<key>NSLocationAlwaysUsageDescription</key>
<string>Your message goes here</string>

or

<key>NSLocationWhenInUseUsageDescription</key>
<string>Your message goes here</string>

Note:

This keys permit to specify the reason for accessing the user’s location information, from iOs 8, containing the message to be displayed to the user at the prompt.

There are two kinds of authorization that you can request:

  • WhenInUse: allow the application to get location updates only when the application is in the foreground.
  • Always: allow the application to receive location updates when the application is in the foreground and in the background.

==> An application can include two plist keys NSLocationAlwaysUsageDescription and NSLocationWhenInUseUsageDescription for either one or both authorization types.

The AdtagBeaconManager will automatically request the authorization to the location manager using these keys, using the following code:

if ([self.locationManager respondsToSelector:@selector(requestWhenInUseAuthorization)]) {
	 [self.locationManager requestWhenInUseAuthorization];
 }

Step 6: Configure the SDK inside the ApplicationQuickStart class

  • Open the class AppDelegate.m
  • Configure the initAdtagInstanceWithUrlType with the received informations from Connecthings:
```objectivec
objectivec : 

  [self initAdtagInstanceWithUrlType:ATUrlTypePreprod
                            userLogin:@"YOUR_USER"
                            userPassword:@"API_KEY"
                            userCompany:@"YOUR_COMPANY_KEY"
                            beaconUuid:@"beaconUuid"];
```

Note: The AdtagInitializer permits to configure the access to the various Adtag platform. 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 1:

Be sure to use the good access key login / password with the appropriate platform - for each platform (Demo/Pre-production/Production) you have received a specific access key.

Warning 2:

Connecthings send you a user to connect to the Adtag Platform and a user with an API KEY to be use with the SDK. Be sure to use the user with the API KEY to connect the SDK to the Adtag Platform, otherwise the application won't detect the beacons.

Warning 3: Connecthings send you two different access keys for each platform: - An access key to sign in the Adtag Platfrom - An access key to use with the SDK mobile, called API_KEY. Be sure to use the correct API KEY (login, password, and platform) to connect the SDK to the Adtag Platform, otherwise the application won't detect the beacons.

Step 7: Start testing

  • Connect your iOS Device to your computer (the device must be registered on Apple’s developers 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 in your console:

"Welcome to Adtag via SDK-Mobile "