Updated to version 3.1.0 of Beemray SDK

1)  Download the Beemray SDK for iOS file

Download the Beemray SDK for iOS and unzip its contents in a local folder, e.g./Users/yourname/Documents/BeemraySDK.

You should have two files: Beemray.framework and Beemray.bundle.

2)  Link against Beemray static framework

1. Drag the Beemray.framework file from Finder into your project in Xcode’s Navigator pane. When asked, tell Xcode to add the files to your main target.

NOTE: When you drag & drop the framework into your project, Xcode sets the appropriate build setting for you. If for any reason this does not happen, you have to do it manually. Go to the Build Settings tab of your main target, look for the entry “Framework Search Paths” and set its value to the directory where the framework is located (e.g./Users/yourname/Documents/BeemraySDK)

2. Go to Build Settings tab of your app target, then search for “Other Linker Flags”. Click the + button, and add a flag with text: -ObjC

3)  Include resources bundle

Drag Beemray.bundle from Finder into your project in Xcode’s Navigator pane, under the “Supporting Files” folder. When asked, tell Xcode to add the files to your main target.

4)  Link against the required dynamic frameworks

Go to the Build Phases tab of your main target. You will see that Beemray.framwork is already added to the “Link Binary With Libraries” section (if not, add it now). Add entries to this section for all the required frameworks. Required frameworks are:

1. Foundation.framework
2. UIKit.framework
3. SystemConfiguration.framework
4. MobileCoreServices.framework
5. CoreLocation.framework
6. AudioToolbox.framework
7. MapKit.framework
8. CoreTelephony.framework
9. CoreBluetooth.framework

5)  Enable background location updates in your app

1. Enable "Background Modes" on the Capabilities tab of your project settings and select the "Location updates" checkbox.
   • NOTE: Alternatively, you can add an entry to your .plist file of type Array and key UIBackgroundModes ("Required background modes"); and add an entry to this array of type String and value location ("App registers for location updates").
2. Add an entry to your app’s .plist file (typically named YourAppName-Info.plist) with key NSLocationAlwaysUsageDescription and type String. As value, provide an informative message such as: “Location is needed to offer you the best promotions”

6)  Enable push notifications in your app

1. Enable "Background Modes" on the Capabilities tab of your project settings and select the "Remote notifications" checkbox.
   • NOTE: Alternatively, you can add an entry to your .plist file of type Array and key UIBackgroundModes ("Required background modes"); and add an entry to this array of type String and value remote-notification ("App downloads content in response to push notifications").
2. Follow Apple’s documentation to configure push notifications. Export your certificates for both development and production as Personal Information Exchange format(.p12 extension). Protect each of them with a password when asked.
3. Log into our Dashboard and go to Settings > Devices
4. Upload your Development and Production certificates (.p12 files) and type the password you chose for each of them (certificates with empty password are not supported)
   
   
   

Using the library

You’ll normally start the Beemray service when your application is launched. In your application delegate (typically AppDelegate.m), add Beemray framework import to the imports section:

...
#import <Beemray/Beemray.h>
...

Add the following code to the application:didFinishLaunchingWithOptions method. The only required configuration parameter is your Beemray API key.

...
/* Create a configuration object with your Beemray API key */
NString *apiKey = @"XXXXXXXXXXXXXXXXXXXXXXXX";
BeemrayConfig *config = [[BeemrayConfig alloc] initWithApiKey:apiKey];

/* Start the service */
[[Beemray sharedInstance] startWithConfiguration:config];

/* Notify app finish launching to Beemray service */
[[Beemray sharedInstance] didFinishLaunchingWithOptions:launchOptions];
...

Finally, add these methods to the application delegate:

- (void)application:(UIApplication *)application didReceiveLocalNotification:(UILocalNotification *)notification{
    [[Beemray sharedInstance] didReceiveLocalNotification:notification];
    /* your code */
}
- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
    [[Beemray sharedInstance] didRegisterForRemoteNotificationsWithDeviceToken:deviceToken];
    /* your code */
}
- (void)application:(UIApplication *)application didFailToRegisterForRemoteNotificationsWithError:(NSError *)error {
    [[Beemray sharedInstance] didFailToRegisterForRemoteNotificationsWithError:error];
    /* your code */
}
- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo
                                                       fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
    [[Beemray sharedInstance] didReceiveRemoteNotification:userInfo fetchCompletionHandler:completionHandler];
    /* your code */ 
}

Advanced configuration

Using the service during app development

On your Development builds (that is, when running the app through Xcode when your phone is plugged), push notifications need to be sent via Apple's Sandbox push server. You must notify this to our backend by setting the development property to YES on the BeemrayConfig object you use to start Beemray service, like this:

...
BeemrayConfig *config = [[BeemrayConfig alloc] initWithApiKey:apiKey];
config.development = YES;
[[Beemray sharedInstance] startWithConfiguration:config];
..

It is important that you do NOT set this property for Ad-Hoc or Production builds (this includes builds sent to App Store or TestFlight).

Tweaking how Beemray behaves 

The class BeemraySettings lets you tweak some settings that may change service behavior. It is used by accessing the settings property of the service.

/** A delegate to receive events that happen during Beemray service
execution. */
[Beemray sharedInstance].settings.delegate;

/** Logging level of the framework. Only log messages with a level
equal or lower than this property are printed. Default: BeemrayLogLevelDebug */
[Beemray sharedInstance].settings.logLevel = BeemrayLogLevelInfo;

/** Language used when presenting UI elements to the user. If not set, the
language defined in the device is used. */
[Beemray sharedInstance].settings.lang = "es";

/** Whether or not notifications are persistent. Persistent
notifications reappear in the notification area even if user deletes
them. Note that this will cause conflicts if the app shows
notifications other than beems. If you want to show your own
notifications, set this property to NO (which is the default). */
[Beemray sharedInstance].settings.persistentNotification = NO;

/** If YES (default), tapping on the notifications will open a separate,
 full-screen window with a beembox with the given beem opened. If NO, the new
 window will display only the tapped beem. This setting has no effect when
 persistentNotification is set to YES. In this case, beembox is always used. */
[Beemray sharedInstance].settings.useBeemBox = NO;

Adding a service start-up callback

The Beemray class also offers a second method to start the service, which executes the given block after service startup. This is its signature:

/** Starts the Beemray service after applying the given configuration.
 After startup process is finished, the given block (if any) is executed. The
 block receives an error as argument only if the startup failed.
 After running the block, either `serviceDidStart:` or
 `serviceStartupFailedWithStatus:error` is called on the delegate.
 If the service is already started, this method has no effect other than executing
 the given block and calling `serviceDidStart:` on the delegate passing `NO` as
 argument. Therefore, in order to update the configuration, the service needs to
 be stopped and started again.
  
 @param config Configuration to apply to the service
 @param block block to execute at the end of startup process. Pass in `nil` if
 you do not want to execute any block
 */
- (void)startWithConfiguration:(BeemrayConfig*)config block:(void(^)(NSError*))block;