TWC Alerting Serivce SDK allows you to integrate extreme weather events notification into your iOS application.

Features:

  • Creating, updating, deleting assets, asset registrations, viewing of available peril groups and perils
  • Tracking and updating user’s location automatically (follow me)

Requirements

  • iOS 8.0+
  • Xcode 8.1+
  • Swift 3.0+ / Objective-C

Installation

Step 1. Configure your application

Visit DeveloperWorks to obtain your access credentials for The Weather Company Alerts

Step 2. Download AlertingSDK for iOS

Step 3. Add sdk to project

  • Go to your target
  • Select General tab
  • Press + button in Embedded Binaries section
  • Press Add Other… in dialog window.
  • Locate and select TWCAlertingSDK.framework you downloaded
  • Check Copy items if needed and click Finish

Step 4. Add stripping script

TWCAlertingSDK.framework is a universal fat binary that supports x86_64 and i386 architectures. in order to submit your app to appStore you will need to add a script that removes this unneeded slices before preparing build for an AppStore.

  • Go to your target
  • Select Build Phases tab
  • Press + button and New run script phase
  • Paste that script into your new run script:
APP_PATH="${TARGET_BUILD_DIR}/${WRAPPER_NAME}"
find "$APP_PATH" -name 'TWCAlertingSDK.framework' -type d | while read -r FRAMEWORK
do
FRAMEWORK_EXECUTABLE_NAME=$(defaults read "$FRAMEWORK/Info.plist" CFBundleExecutable)
FRAMEWORK_EXECUTABLE_PATH="$FRAMEWORK/$FRAMEWORK_EXECUTABLE_NAME"
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
lipo -o "$FRAMEWORK_EXECUTABLE_PATH-merged" -create "${EXTRACTED_ARCHS[@]}"
rm "${EXTRACTED_ARCHS[@]}"
rm "$FRAMEWORK_EXECUTABLE_PATH"
mv "$FRAMEWORK_EXECUTABLE_PATH-merged" "$FRAMEWORK_EXECUTABLE_PATH"
done

Setup

Step 1. Setup you XCode project

If you are going to use built in Follow me feature for automatic user tracking and updating, you will need to do following:

Note

If you link your app against iOS 11 and higher, you must provide NSLocationAlwaysAndWhenInUseUsageDescription key with description.

  1. Open your target’s Info section:

    • Add Privacy - Location Always Usage Description key into Custom iOS Target Properties.
    • Add usage description to it. For example: We will use your location, to notify you about upcoming extreme weather events nearby
    • For iOS 11 support, you must add Privacy - Location When In Use Usage Description key into Custom iOS Target Properties with a description.

  2. Open your target’s Capabilities section and turn Background Modes - ON. Open Background modes dropdown menu and check Location updates.

Note

If you are going to update user’s location manually, you do not need to perform those steps above.

Step 2. Setup your AppDelegate

  1. Add import TWCAlertingSDK
  2. Add to your AppDelegate's application(_ application: didFinishLaunchingWithOptions:):
  3. let alertingSerivce = AlertingService()
  4. alertingSerivce.setup(clientId: "put your id here", clientSecret: "put your secret here", launchOptions: launchOptions)

import UIKit
import TWCAlertingSDK

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {

    var window: UIWindow?

    let IBMClientId     = "your_client_id"
    let IBMClientSecret = "your_client_secret"
    let alertingService = AlertingService()

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
        alertingService.setup(clientId: IBMClientId, clientSecret: IBMClientSecret, launchOptions: launchOptions)
        return true
    }
}

Note

You can add a property to your AppDelegate or create a helper class for storing and working with your AlertingSerivce instance.

Now you can work with your alerting service instance. Before turning follow me feature on, you will need to create an asset and register it. For more details see AlertingService class documentation.

Step 3. Listening to events (optional)

You can subscribe to AlertingSeviceNotifications notifications to catch events from AlertingService. For more details see Logging tutorial.

Quick Start

You can skip Asset creation and registration steps, simply by calling quickStart method.

alertingService.quickStart(with: AlertingService.kQuickStartAddressPushToken, successHandler: {
    // Success, registered for Remote Push Notifications, Follow Me - On
}) { (apiError, error) in
    // Handle errors here
}

Note

You can specify delivery address (phone number or email), starting location to use as initial Asset location, set followMe to false if you don’t want to enable it instantly, list PerilGroups if you don’t want to register for all of them. By omitting those parameters, quickStart will try to get current device location, register for all peril groups and will turn Follow Me on.

Notes

  • In order to let SDK work in background mode app should have Background App Refresh permission.
  • In order to let SDK work in background mode app should have Location Always Usage permission.
  • SDK will track significant location change, approximately once every 500 metres.

Usage Notice

IBM is delivering Weather Company Alerts Alerting SDK and Mobile Support Add-on to Client for further development, build and test. Client understands and confirms that further development (whether performed by the Client or by IBM acting on the Client’s behalf) is undertaken under the Client’s Apple Developer or Developer Enterprise Program Agreement.

The Client confirms that they have all appropriate Apple developer program license(s) and that the Client, as Apple’s licensee, is subject to, and will comply with, the terms of the appropriate Apple developer program agreement.