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
file from Finder into your project in Xcode’s Navigator pane. When asked, tell Xcode to add the files to your main target.Beemray.framework
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:
- Foundation.framework
- UIKit.framework
- SystemConfiguration.framework
- MobileCoreServices.framework
- CoreLocation.framework
- AudioToolbox.framework
- MapKit.framework
- CoreTelephony.framework
- CoreBluetooth.framework
5) Enable background location updates in your app
- 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 typeArray
and keyUIBackgroundModes
("Required background modes"); and add an entry to this array of typeString
and valuelocation
("App registers for location updates").
- NOTE: Alternatively, you can add an entry to your
- Add an entry to your app’s .plist file (typically named
YourAppName-Info.plist
) with keyNSLocationAlwaysUsageDescription
and typeString.
As value, provide an informative message such as: “Location is needed to offer you the best promotions”
6) Enable push notifications in your app
- 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 typeArray
and keyUIBackgroundModes
("Required background modes"); and add an entry to this array of typeString
and valueremote-notification
("App downloads content in response to push notifications").
- NOTE: Alternatively, you can add an entry to your
- 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. - Log into our Dashboard and go to Settings > Devices
- 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;
Comments