Overview

This document describes how to integrate Optimise AppButton in your iOS Application. The following details how to integrate the SDK, add a placement and display a button in your app.

Prerequisites

  1. You must have an understanding of developing iOS Apps.
  2. You must be familiar with Objective-C/Swift as development environment.

Adding the SDK to your App

1. Add the AppButtonSdk.Framework

Drag and drop library AppButtonSDK.framework in project as shown below.

ios-appbutton-sdk1

2. Link library to project

Select TARGETS under the General tab and click on ‘+’ in Embedded Binaries.

ios-appbutton-sdk2

3. Select AppButtonSDK.framework

Select AppButtonSDK.framework and click on Add

ios-appbutton-sdk3

4. Add Script to remove unsupported binaries

To remove unsupported binaries architecture from SDK, please follow the steps mentioned below

4.1 Select New Run Script Phase

Select ‘TARGETS’ under ‘Build Phases’ tab, click on ‘+’ icon and select ‘New Run Script Phase’ as shown below.

ios-appbutton-sdk4

4.2 Add Script

Copy and paste the following script:

APP_PATH="${TARGET_BUILD_DIR}/${WRAPPER_NAME}"
# This script loops through the frameworks embedded in the application and
# removes unused architectures.
find "$APP_PATH" -name '*.framework' -type d | while read -r FRAMEWORK
do
FRAMEWORK_EXECUTABLE_NAME=$(defaults read "$FRAMEWORK/Info.plist" CFBundleExecutable)
FRAMEWORK_EXECUTABLE_PATH="$FRAMEWORK/$FRAMEWORK_EXECUTABLE_NAME"
echo "Executable is $FRAMEWORK_EXECUTABLE_PATH"
 
EXTRACTED_ARCHS=()
 
for ARCH in $ARCHS
do
echo "Extracting $ARCH from $FRAMEWORK_EXECUTABLE_NAME"
lipo -extract "$ARCH" "$FRAMEWORK_EXECUTABLE_PATH" -o
 
 
"$FRAMEWORK_EXECUTABLE_PATH-$ARCH"
EXTRACTED_ARCHS+=("$FRAMEWORK_EXECUTABLE_PATH-$ARCH")
done
 
echo "Merging extracted architectures: ${ARCHS}"
lipo -o "$FRAMEWORK_EXECUTABLE_PATH-merged" -create "${EXTRACTED_ARCHS[@]}"
rm "${EXTRACTED_ARCHS[@]}"
echo "Replacing original executable with thinned version"
rm "$FRAMEWORK_EXECUTABLE_PATH"
mv "$FRAMEWORK_EXECUTABLE_PATH-merged" "$FRAMEWORK_EXECUTABLE_PATH"
done

Ensure the checkbox  is checked as shown below:

ios-appbutton-sdk5

5. Add Application query schemes

You will need to modify your application’s Info.plist to handle Apple’s new security changes. Locate the Info.plist file for your application (usually found in the Supporting Files folder). Right-click this file and select Open As > Source Code and add the following code snippet.

<key>LSApplicationQueriesSchemes</key>
<array>
<string>AppScheme 1</string>
<string>AppScheme 2</string>
</array>

AppScheme is the URLScheme of linked Advertiser to AppButton.

ios_appbutton_sdk_query_schemes

6. Initialize the SDK

Choose your development language:

6.1 Objective-C Support

If you have developed your app in Objective-C than please complete the following otherwise move to step 4.2.

Import sdk header file.

Example: #import <AppButtonSDK/AppButtonSDK.h>

ios-appbutton-sdk6

6.1.1 Create the SDK Instance and set Global variable

Call the following method of AppButtonSDK to create the instance of ButtonManager.

// create instance of buttonManager
ButtonManager  *buttonManager = [ButtonManager sharedManager];
// appid is a global variable.
[buttonManager setAppID:@" appId"];

ButtonManagerThis is the main class of the SDK. Create an instance of this class to call initWithPlacements and create a buttonPlacement. For example:

//set userlocation coordinate's (Latitude and Longitude) as string
BTNUserLocation *uLocation = [[BTNUserLocation alloc] initWithLatitude:@"28.41868" logitude:@"77.038411"];
 
//set itemlocation coordinate's (Latitude and Longitude) as string
BTNItemLocation *iLocation = [[BTNItemLocation alloc] initWithLatitude:@"28.5562"  logitude:@"77.1"];
 
//set button context. Send userLocation and itemLocation with userLocaltime.
//userLocaTime is current time of device. Date format "yyyy-MM-dd'T'HH:mm:ssZ".
BTNContext *context = [[BTNContext alloc] initWithUserLocation:uLocation  itemLocation:iLocation userLocalTime:@"2017-05-02T08:43:32.400Z"];
 
BTNPlacement *placement = [[BTNPlacement alloc] initWithContext:context wherePlacementID:@"1"];
[placement addUID:@"TEST"];
[placement addUID:@"TEST1"];
  • BTNUserLocation – BTNUserLocation class holds the value of latitude and longitude. BTNUserLocation reference will be the current location coordinates value. You must pass the reference of this class in BTNContext.
  • BTNItemLocation – BTNItemLocation class holds the value of latitude and longitude. BTNItemLocation reference will be the destination location coordinates value. You must pass the reference of this class in BTNContext.
  • BTNItemProperties – BTNItemProperties class holds the search keywords. You must pass an array of string in keywords parameter. Pass itemProperties reference in BTNContext.
  • BTNContext – BTNContext class holds the reference of userLocation, itemlocation and itemProperties. You must pass these as a parameter to this class as per the required button.
  • BTNPlacement – BTNPlacement class holds the reference of BTNContext. You must pass BTNContext with placementId as a parameter to this class. PlacementId parameter will be provided to you by Optimise. You can create multiple BTNPlacement’s as per the requirement.
  • Placement – OptimisePlacement class is a subclass of UIView. It is a view container in which the button will be displayed. You can display multiple buttons in one placement. You just need to create an instance of this class and set the view frame where you want to display it in the UI. Call the method of this class after completion of initWithPlacements method. Before calling this method please check completion is completed, meaning the request is successful. You can see an example below.
// call to "initWithPlacements" instance method of ButtonManager.
// pass placement in an array. you can pass multiple button placement.
[buttonManager initWithPlacements:[NSArrayarrayWithObjects:placement, nil]   completion:^(BOOL completed) {
 
if (completed) {
Placement *listPlacement = [[Placement alloc] initWithFrame:CGRectMake(8,160,200,40) placementId:@"1"];
listPlacement.backgroundColor = [UIColor whiteColor];
[self.view addSubview:listPlacement];
}
}];

If you want to create  a retail-led button like then create BTNContext as shown in the below example.

BTNItemProperties *itemProperties = [[BTNItemProperties alloc] initWithKeywords:@[@"tv sony"]];
BTNContext *ctx1 = [[BTNContext alloc] initWithItemProperties:itemProperties userLocalTime:@"2017-05-08 08:38:55.021"];

Call BTNContext method initWithItemProperties and create context and pass context in BTNplacement.

Class Method Parameter Description
ButtonManager  +(instancetype) sharedManager; This is the main class of SDK. This method create instance of ButtonManger class.
ButtonManager -(void) initWithPlacements:(NSArray <BTNPlacement *>*)placements completion:(void (^) (BOOL completed))completion; NSArray Pass Array of BTNPlacement.
BTNUserLocation -(instancetype)initWithLatitude:(NSString*) lat  longitude:(NSString *)long; Latitude, Longitude Pass user’s current location in this method. The parameters are latitude, longitude.
BTNItemLocation -(instancetype)initWithLatitude:(NSString*) lat  longitude:(NSString *)long; Latitude, Longitude Pass the item’s location to this method. The parameters are latitude, longitude.
BTNItemProperties -(instancetype)initWithKeywords:(NSArray *) keywords; keywords Pass an array of string’s keyword as a parameter.
BTNContext -(instancetype)initWithUserLocation:(BTNUserLocation *)userLocation itemLocation:(BTNItemLocation *)itemLocation userLocalTime:(NSString *)time; userLocation, itemLocation, userLocalTime BTNContext class hold value of UserLocation, itemLocation and userLocalTime.
userLocation is an instance of BTNUserLocation class.
itemLocation is an instance of BTNItemLocation class.
localTime is current time of device.
BTNContext -(instancetype)initWithItemProperties:(BTNItemProperties *)itemProperties userLocalTime:(NSString *)time; itemProperties, userLocalTime This method is used to add retail-led buttons.
itemProperties is a BTNItemProperties instance.
localTime is current time of device.
BTNPlacement  -(instancetype)initWithContext:(BTNContext *)context wherePlacementID:(NSString *)placementID;  Context, placementID Pass the ButtonPlacement instance to this method and placementID.
BTNPlacement -(void)addUID:(NSString *)uid; uid (NSString) This is an optional method. Pass a unique identifier here. You can set maximum of 5 UID’s per placement.
Placement  -(id)initWithFrame:(CGRect)frame placementId:(NSString *)placementID;  CGRect, placementID  Pass the ButtonPlacement instance to this method and placementID.

ios-appbutton-sdk7

6.2 Swift Support

If you are using Swift as your development environment, please follow the below steps.

6.2.1 Create a Bridging Header File

Select ‘New File’ header file as shown below and click NEXT.

ios-appbutton-sdk8

6.2.2 Add Name of header file

Give name of the HeaderFile “YourAppName-Bridging-Header.h” as shown below.

ios-appbutton-sdk9

6.2.3 Set the path of your bridging file

Select ‘TARGETS’> select Build Settings> select Objective-c Bridging Header and set path of bridging file. “YourAppName/BridgingHeaderFileName” as shown below.

ios-appbutton-sdk10

6.2.4 Import framework

Import framework as shown below.

ios-appbutton-sdk11

6.2.5 Initialize SDK

Create instance of SDK Manager and call methods as shown below.

ios-appbutton-sdk12

let sdkmanager = ButtonManager.shared()
let ul = BTNUserLocation.init(latitude: "28.41868", logitude: "77.038411")
let il = BTNItemLocation.init(latitude: "28.5562", logitude: "77.1")
let ctx2 = BTNContext.init(userLocation: ul, itemLocation: il, userLocalTime: "2017-05-02T08:43:32.400Z")
let plc2 = BTNPlacement.init(context: ctx2, wherePlacementID: "1")
let ary: [BTNPlacement] = [plc1!,plc2!]
 
sdkmanager?.initWithPlacements(placements: ary, completion: { (Bool) in
if(Bool){
let op = Placement.init(frame: CGRect(x: 8, y: 160, width: 200, height: 100), placementId: "1")
op?.backgroundColor = UIColor.white
self.view.addSubview(op!)
}
})