Swiftpack.co - ably/ably-asset-tracking-swift as Swift Package

Swiftpack.co is a collection of thousands of indexed Swift packages. Search packages.
See all packages published by ably.
ably/ably-asset-tracking-swift v1.0.0-rc.1
iOS client SDKs for the Ably Asset Tracking service.
⭐️ 6
🕓 6 weeks ago
iOS
.package(url: "https://github.com/ably/ably-asset-tracking-swift.git", from: "v1.0.0-rc.1")

Ably SDK

Ably is the platform that powers synchronized digital experiences in realtime. Whether attending an event in a virtual venue, receiving realtime financial information, or monitoring live car performance data – consumers simply expect realtime digital experiences as standard. Ably provides a suite of APIs to build, extend, and deliver powerful digital experiences in realtime for more than 250 million devices across 80 countries each month. Organizations like Bloomberg, HubSpot, Verizon, and Hopin depend on Ably's platform to offload the growing complexity of business-critical realtime data synchronization at global scale. For more information, see the Ably documentation.

Ably Asset Tracking SDKs for Swift

.github/workflows/check.yml

Overview

Ably Asset Tracking SDKs provide an easy way to track multiple assets with realtime location updates powered by the Ably realtime network and Mapbox Navigation SDK with location enhancement.

Status

This SDK is a beta version. That means it contains a subset of the final SDK functionality, and the APIs are subject to change. The latest release of the SDKs is available in the Releases section of this repository.

Ably Asset Tracking is:

  • easy to integrate - comprising two complementary SDKs with easy to use APIs, available for multiple platforms:
  • Asset Publishing SDK, for embedding in apps running on the courier's device.
  • Asset Subscribing SDK, for embedding in apps running on the customer's observing device.
  • extensible - as Ably is used as the underlying transport, you have direct access to your data and can use Ably integrations for a wide range of applications in addition to direct realtime subscriptions - examples include:
  • passing to a 3rd party system
  • persistence for later retrieval
  • built for purpose - the APIs and underlying functionality are explicitly designed to meet the requirements of a range of common asset tracking use-cases

This repo holds an Xcode workspace (Examples/AblyAssetTracking.workspace), containing:

Multiple example apps/ Xcode projects, and

One Swift Package (ably-asset-tracking-swift), containing three libraries/ SDKs:

  • Publisher SDK: The AblyAssetTrackingPublisher library allows you to use import AblyAssetTrackingPublisher.

  • Subscriber SDK: The AblyAssetTrackingSubscriber library allows you to use import AblyAssetTrackingSubscriber.

  • Ably Asset Tracking UI SDK: The AblyAssetTrackingUI library allows you to use import AblyAssetTrackingUI.

    The UI SDK contains:

    • Location Animator - uses to animate map view annotation smoothly

Documentation

Visit the Ably Asset Tracking documentation for a complete API reference and code examples.

Useful Resources

Installation

Requirements

These SDKs support support iOS and iPadOS. Support for macOS/ tvOS may be developed in the future, depending on interest/ demand.

  • Publisher SDK: iOS 12.0+ / iPadOS 12.0+

  • Subscriber SDK: iOS 12.0+ / iPadOS 12.0+

  • Xcode 12.4+

  • Swift 5.3+

Swift package manager

  • To install this package in an Xcode Project:
  • Paste https://github.com/ably/ably-asset-tracking-swift in the "Swift Packages" search box. (Xcode project > Swift Packages.. > + button)
  • Select the relevant SDK for your target. (Publisher SDK, Subscriber SDK or both)
  • This apple guide explains the steps in more detail.
  • To install this package into a Swift Package, add the following to your manifest (Package.swift):
.package(url: "https://github.com/ably/ably-asset-tracking-swift", from: LATEST_VERSION),

You can find the version on the releases page.

Example Apps

  • Configure your Mapbox credentials (~/.netrc) to download the Mapbox SDK by following this guide. You'll need a Mapbox account.
  • An Examples/Secrets.xcconfig file containing credentials (keys/ tokens) is required to build the example apps. (You can use the example Examples/Example.Secrets.xcconfig, e.g. by running cp Examples/Example.Secrets.xcconfig Examples/Secrets.xcconfig). Update the following values in Examples/Secrets.xcconfig:
  • ABLY_API_KEY: Used by all example apps to authenticate with Ably using basic authentication. Not recommended in production, and can be taken from here.
  • MAPBOX_ACCESS_TOKEN: Used to access Mapbox Navigation SDK/ APIs, and can be taken from here. Using the Mapbox token is only required to run the Publisher example apps.
  • Open AblyAssetTracking.xcworkspace to open an Xcode workspace containing the Subscriber example app and the Swift Package containing the SDKs that showcase how to use the subscriber part of the Ably Asset Tracking SDKs.
  • Open PublisherExampleSwiftUI.xcodeproj to open an Xcode workspace containing the Publisher exmple app

Usage

Publisher SDK

The Asset Publisher SDK can efficiently acquire the location data on a device and publish location updates to other subscribers in realtime. Here is an example of how the Asset Publisher SDK can be used:

import AblyAssetTrackingPublisher

// Initialise a Publisher using the mandatory builder methods

publisher = try? PublisherFactory.publishers() // get a Publisher Builder
    .connection(ConnectionConfiguration(apiKey: ABLY_API_KEY, clientId: CLIENT_ID)) // provide Ably configuration with credentials
    .delegate(self) // provide delegate to handle location updates locally if needed
    .start()
    
// Start tracking an asset

publisher?.track(trackable: Trackable(id: trackingId)) // provide a tracking ID of the asset

See the PublisherBuilder protocol for addtional optional builder methods.

Subscriber SDK

The Asset Subscriber SDK can be used to receive location updates from a publisher in realtime. Here is an example of how Asset Subscribing SDK can be used:

import AblyAssetTrackingSubscriber

// Initialise a Subscriber using the mandatory builder methods

subscriber = try? SubscriberFactory.subscribers() // get a Subscriber Builder
    .connection(ConnectionConfiguration(apiKey: ABLY_API_KEY, clientId: CLIENT_ID)) // provide Ably configuration with credentials
    .trackingId(trackingId) // provide a Tracking ID for the asset to be tracked
    .delegate(self) // provide delegate to handle location updates locally if needed
    .start() // start listening to updates

See the SubscriberBuilder protocol for addtional optional builder methods.

Authentication

Both Subscriber and Publisher SDK support basic authentication (API key) and token authentication. Specify this by passing a ConnectionConfiguration to the Subscriber or Publisher builder: SubscriberFactory.subscribers().connection(connectionConfiguration).

To use basic authentication, set the following ConnectionConfiguration on the Subscriber or Publisher builder:


let connectionConfiguration = ConnectionConfiguration(apiKey: ABLY_API_KEY, clientId: clientId)

To use token authentication, you can pass a closure which will be called when the Ably client needs to authenticate or reauthenticate:

let connectionConfiguration = ConnectionConfiguration(clientId: clientId) { tokenParams, resultHandler in

    // Implement a request to your servers which provides either a TokenRequest (simplest), TokenDetails, JWT or token string.

    getTokenRequestJSONFromYourServer(tokenParams: tokenParams) { result in
        switch result {
        case .success(let tokenRequest):
            resultHandler(.success(.tokenRequest(tokenRequest)))
        case .failure(let error):
            resultHandler(.failure(error))
        }
    }
}

Alternatively, in token authentication, you can specify an authUrl, which will be used by Ably to authenticate.

let connectionConfiguration = ConnectionConfiguration(authUrl: authUrl, clientId: clientId)

Ably Asset Tracking UI (Location Animator)

The Location Animator can interpolate and animate map annotation view.

// Instantiate Location Animator
let locationAnimator = DefaultLocationAnimator()
// Subscribe for `Location Animator` position updates
locationAnimator.subscribeForFrequentlyUpdatingPosition { position in
    // Update map view annotation position here
}
// Additionally you can subscribe for infrequently position updates
locationAnimator.subscribeForInfrequentlyUpdatingPosition { position in
    // Update map camera position
}
var locationUpdateIntervalInMilliseconds: Double

func subscriber(sender: Subscriber, didUpdateDesiredInterval interval: Double) {
    locationUpdateIntervalInMilliseconds = interval
}
// Feed animator with location changes from the `Subscriber SDK`
func subscriber(sender: Subscriber, didUpdateEnhancedLocation locationUpdate: LocationUpdate) {
    locationAnimator.animateLocationUpdate(location: locationUpdate, expectedIntervalBetweenLocationUpdatesInMilliseconds: locationUpdateIntervalInMilliseconds)
}

Resources

Feature Support

iOS Client Library feature support matrix.

Support, feedback and troubleshooting

Please visit http://support.ably.com/ for access to our knowledgebase and to ask for any assistance.

You can also view the community reported Github issues.

To see what has changed in recent versions, see the CHANGELOG.

Known Limitations

These SDKs support iOS and iPadOS. Support for macOS / tvOS may be developed in the future, depending on interest / demand.

Contributing

For guidance on how to contribute to this project, see CONTRIBUTING.md.

GitHub

link
Stars: 6
Last commit: 2 days ago
jonrohan Something's broken? Yell at me @ptrpavlik. Praise and feedback (and money) is also welcome.

Release Notes

1.0.0, Release Candidate 1
6 weeks ago

Full Changelog

Implemented enhancements:

  • Enable setting a constant location engine resolution #276
  • Add ability to observe raw locations change in Subscriber SDK #272
  • Send batches of location updates #265
  • Upgrade Mapbox dependencies #260
  • Display resolution information in the subscriber example app #254
  • Send resolution to subscriber #253
  • Add switch enabling raw locations publishing in the publisher example app #252
  • Add raw locations to the Subscriber SDK #251
  • Send raw locations from the Publisher #250
  • Implement RSC7d (Ably-Agent header) #172
  • Implement stopping strategy #165
  • Send skipped location updates #135
  • Add token based authentication #134
  • Modify Publisher example app to work in background #110

Fixed bugs:

  • Subscriber: no asset connection status changes #314
  • Publisher.track method doesn't work as described in the code docs #308
  • Remove fastlane #202
  • DefaultAblyPublisherService never calls .success on channel publish #190
  • Add AAT library versioning #189
  • Specify channel modes to limit the amount of unnecessary data being sent and received over Ably #179
  • Release to Swift Package Manager (SPM) #148
  • Change names of client type values from presence data #136
  • EnhancedLocationUpdateMessage should be sent and received as a single message, not an array. #126
  • Use Ably and channel state when determining the trackable state in the Subscriber and Publisher SDK #120
  • The trackable state should be updated in the Publisher only after the state is different from the previous one. #115
  • Allow to call Publisher track() method multiple times #112
  • Handle stopped state of the Subscriber #109

Closed issues:

  • Update ably-cocoa dependency #299
  • Update Subscriber observer method for location change (enhanced & raw) from publisher #285
  • Add next location update intervals to the Subscriber API #280
  • Remove Swift version of Publisher Example App #278
  • Replace CLLocation with AAT Wrapper Location in subscriber delegate #267
  • Use the next location update intervals to make the marker movement smoother in the example app #263
  • Display the horizontal accuracy of locations in the subscriber example app #257
  • Check: Zooming does not improve resolution: Resolution-type events does not get sent #255
  • Update metadata format pushed with location update #246
  • Created the SwiftUI example app #231
  • Change Codable classes to structs #222
  • Remove Objective-C compatibility #218
  • We need to check how Swift-idiomatic the library is #217
  • Make ConnectionConfiguration initialiser visible in Objective-C #192
  • Handle exception thrown when sending enhanced location update fails #178
  • Create code snippets for landing page #173
  • Supporting location button (in SDK and Example apps) #160
  • Send notification about trip started on a meta channel (iOS) #158
  • Error nw_protocol_get_quic_image_block_invoke dlopen libquic failed when running app #157
  • Renaming to ably-asset-tracking-swift #151
  • Expose EnhancedLocationUpdate in the API instead of CLLocation #150
  • Replace CLLocation type with our own location type #141
  • Remove battery level from location / location update API #140
  • Channel Namespace #139
  • Remove unused metadata field from the Trackable class #133
  • Use different approach of passing class name for debugger instead of using literal string. #127
  • Handle errors when starting Subscriber and Publisher #121
  • Subscriber should be able to request no resolution after creation #119
  • Decide if the start method of Publisher and Subscriber SDKs should be async #117
  • Subscriber should be able to request no resolution after creation #116
  • Handle resolutions for the location engine in the Publisher #113
  • Change stop method in Subscriber SDK to an asynchronous one #108
  • Investigate use of publisherService didFailWithError #103
  • Better approach for Objective-C facade #102
  • Check ErrorInformation alignment with Android codebase #101
  • Unify the way of parsing enums sent over Ably channels across all platforms #99
  • Trackables should be comparable by id, not by all fields #92
  • Reflect tracked asset state in publisher example app #89
  • iOS: Send elevation and battery level of the device as part of the update #84
  • Clear and visible UI indications onSuccess and onFailure #76
  • Create a project with snippets of Objective-C code calling our SDKs #74
  • iOS: Remove sending raw updates from the publisher SDK #73
  • Use AssetTrackingError where possible #66
  • Create ARTRealtime instances with clientId parameter #65
  • Adopt callback interface changes from Android - single handler, not discrete onSuccess and onError #64
  • Accept new LocationUpdate format on the Subscriber side #63
  • Handle Publisher.stop() correctly #51
  • Unify approach for AblyConnectionStatus on iOS and Android #23
  • Use same debug GPS paths on iOS and Android (S3) #16
  • Add check for GeoJSONMessage correctness when initialized from CLLocation #10

Merged pull requests:

Swiftpack is being maintained by Petr Pavlik | @ptrpavlik | @swiftpackco | API | Analytics