Swiftpack.co - Package - box/box-ios-sdk

BoxSDK

Platforms License Swift Package Manager Carthage compatible CocoaPods compatible Build Status Coverage Status

Box Swift SDK

Requirements

  • iOS 11.0+ / Mac OS X 10.13+ / tvOS 11.0+ / watchOS 4.0+
  • Xcode 10.0+

Installing the SDK

Carthage

Step 1: Add to your Cartfile

git "https://github.com/box/box-ios-sdk.git" ~> 3.0

Step 2: Update dependencies

$ carthage update --platform iOS

Step 3: Drag the built framework from Carthage/Build/iOS into your project.

For more detailed instructions, please see the official documentation for Carthage.

CocoaPods

Step 1: Add to your Podfile

pod 'BoxSDK', '~> 3.0'

Step 2: Install pod by running the following command in the directory with the Podfile

$ pod install

For more detailed instructions, please see the official documentation for Cocoapods.

Swift Package Manager

Importing BoxSDK into Project

Step 1: Click on Xcode project file

Step 2: Click on Swift Packages and click on the plus to add a package

Step 3: Enter the following repository url https://github.com/box/box-ios-sdk.git and click next

Step 4: Leave the default settings to get the most recent release and click next to finish importing

The process should look like below:

Import Package

Adding BoxSDK as a Dependency

For detailed instructions, please see the official documentation for SPM.

Getting Started

To get started with the SDK, get a Developer Token from the Configuration page of your app in the Box Developer Console. You can use this token to make test calls for your own Box account.

import BoxSDK

let client = BoxSDK.getClient(token: "YOUR_DEVELOPER_TOKEN")
client.users.getCurrentUser() { result in
    switch result {
    case let .error(error):
        print("Error: \(error)")
    case let .success(user):
        print("\(user.name) (\(user.login)) is logged in")
    }
}

Sample Apps

OAuth2 Sample App

A sample app using OAuth2 Authentication can be found in the repository here. This app demonstrates how to use the SDK to make calls, and can be run directly by entering your own credentials to log in.

To execute the sample app: Step 1: Run carthage

$ cd SampleApps/OAuth2SampleApp
$ carthage update --platform iOS

Step 2: Open Xcode Project File

$ open OAuth2SampleApp.xcodeproj

Step 3: Insert your client ID and client secret

First, find your OAuth2 app's client ID and secret from the Box Developer Console. Then, add these values to the sample app in the Constants.swift file in the sample app:

static let clientId = "YOUR CLIENT ID GOES HERE"
static let clientSecret = "YOUR CLIENT SECRET GOES HERE"

Step 4: Set redirect URL

Using the same client ID from the previous step, set the redirect URL for your application in the Box Developer Console to boxsdk-<<YOUR CLIENT ID>>://boxsdkoauth2redirect, where <<YOUR CLIENT ID>> is replaced with your client ID. For example, if your client ID were vvxff7v61xi7gqveejo8jh9d2z9xhox5 the redirect URL should be boxsdk-vvxff7v61xi7gqveejo8jh9d2z9xhox5://boxsdkoauth2redirect

Step 5: Insert your client ID to receive the redirect in the app

Open the Info.plist file in the sample app and find the key under URL Types --> Item 0 --> URL Schemes --> Item 0. Using the same client ID from the previous step, set the value for Item 0 to boxsdk-<<YOUR CLIENT ID>>, where <<YOUR CLIENT ID>> is replaced with your client ID. For example, if your client ID were vvxff7v61xi7gqveejo8jh9d2z9xhox5 the redirect URL should be boxsdk-vvxff7v61xi7gqveejo8jh9d2z9xhox5

location to add redirect URL scheme in Xcode

Step 6: Run the sample app

JWT Auth Sample App

A sample app using JWT Authentication can be found in the repository here. This app demonstrates how to set up JWT authentication with a remote authorization service, and will not run until you provide the code to retrieve tokens.

To execute the sample app: Step 1: Run carthage

$ cd SampleApps/JWTSampleApp
$ carthage update --platform iOS

Step 2: Open Xcode Project File

$ open JWTSampleApp.xcodeproj

Step 3: Insert your client ID and client secret

First, find your OAuth2 app's client ID and secret from the Box Developer Console. Then, add these values to the sample app in the Constants.swift file in the sample app:

static let clientId = "YOUR CLIENT ID GOES HERE"
static let clientSecret = "YOUR CLIENT SECRET GOES HERE"

Step 4: Add code for retrieving access tokens

In the ViewController.swift file in the sample app, edit the obtainJWTTokenFromExternalSources() method:

func obtainJWTTokenFromExternalSources() -> DelegatedAuthClosure {
    return { uniqueID, completion in
        #error("Obtain a JWT Token from your own service or a Developer Token for your app in the Box Developer Console at https://app.box.com/developers/console and return it in the completion.")
        // The code below is an example implementation of the delegate function
        // Please provide your own implementation
        
        // ...
    }
}

Step 5: Run the sample app

Release Definitions

Starting Oct 19th, 2019 the Box Swift SDK for iOS will be available for general use. This implies all Box developers will be able to use the SDK to build native iOS applications on Box. Between now and the next couple of months, we will be making frequent updates to the SDK based on feedback from our customers, and this document aims to set expectations with respect to:

  1. the various release types you will see over the next few months, what they mean and how to identify them
  2. support policy for each of the release types

Between now and the next couple of months, the Box Swift SDK for iOS releases will be one of the following types:

Release Candidate (RC)

The initial releases of the SDK starting Oct 19th will be Release Candidate (RC). This means (1) the core functionality is present and tested, (2) additional functionality from this point on will be considered improvements or enhancements based on customer feedback. RC releases are usually more frequent (every few weeks), followed shortly by a current release. If you plan to use an RC release, we recommend:

  • that you don't use it for production workloads (If that is unavoidable, we recommend upgrading to the Current Release version once it's ready.)
  • that you create a plan to keep your application on the latest RC release version at all times (since older RC releases are considered "out of support" as soon as a new RC release is released)

Also, RC releases may carry breaking changes from the previous release and we advise developers to test their application adequately with the new RC release before adopting it.

The idea behind releasing RC releases is to rapidly iterate on the SDK (bug fixes, feature tweaks, etc.) to get it to a production-ready state, and typically we don't expect to have the SDK in the RC phase for more than a month.

Support for RC releases

A RC release

  • is Considered Active when released
  • transitions to End-of-life when the next release becomes Active

Current Release

A Current Release is considered more stable that a Release Candidate Release and for that reason we expect less frequent releases of a Current Release. We typically expect to refresh Current Releases approximately every 3 months (could be shorter or longer depending on the criticality of the contents of the release).

A new Current Release will usually carry new functionality, bug fixes and may contain breaking changes. We will call out all breaking changes (if any) in the Release Notes section of every Current Release, and we advise developers to test their application adequately before adopting in for production use. 

A Current release is on the leading edge of our SDK development, and is intended for customers who are in active development and want the latest and greatest features.  Current releases are not intended for long-term use, and will only receive enough support after the next release becomes available to allow for a smooth transition to the new version. 

Support for Current Release

A Current Release

  • is Considered Active when released
  • transitions to Maintenance 3 months after it becomes Active, or when the next release becomes Active, whichever is later
  • reaches End-of-life 6 months after it becomes Active, or 3 months after the next release becomes Active, whichever is later

Long Term Support

A Long-Term Support (LTS) release is one which we plan to guarantee compatibility with for an extended period of time.  The public interfaces of the SDK should not be changed in ways that would break customers’ application, and the release should continue to receive at least bug fixes for its entire lifecycle. We expect to refresh Long Term Release version every 18 - 24 months.

For the above reasons, we recommend all developers who do not intend to make frequent updates (~every 6 - 12 months) to their application, only use a Long Term Release version of the SDK. 

Support for Long Term Release

A Long Term Release

  • is considered Active when released
  • transitions to Maintenance 1 year after it becomes Active, or when the next release becomes Active, whichever is later
  • reaches End-of-life 2 years after it becomes Active, or 1 year after the next LTS release becomes Active, whichever is later

Support Phases

Active

Once a release is considered ready for release, a new version is cut and the release enters the Active phase.  However, new features may be added to the SDK, including support for new API endpoints. 

Maintenance

After a time, the release is no longer under active development, but customers may still be depending on it.  At this time, we consider the release to be in Maintenance phase; generally, only bug fixes will be considered for inclusion in new versions.  We may of course opt to include new functionality based on customer demand, but in general customers should expect that the SDK feature set will be mostly frozen for the remainder of its lifecycle.

End-of-life

After a release is no longer being supported by Box, it enters End-of-life (EOL) and no further changes should be expected by customers.  Customers must upgrade to a newer release if they want to receive support.

Copyright and License

Copyright 2019 Box, Inc. All rights reserved.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Github

link
Stars: 74
Help us keep the lights on

Dependencies

Releases

v3.0.0 - Nov 20, 2019

Box iOS SDK

Breaking Changes:

New Features and Enhancements:

  • Added file specific icons for the Sample Apps

v3.0.0-rc.3 - Nov 15, 2019

Box iOS Swift SDK Release Candidate

Notes:

  • The source code for this Box iOS Swift SDK is now open source and included in this release.
  • The releases will no longer have the Box iOS Swift SDK binaries attached, going forward.
  • In order to build the Box iOS Swift SDK project, clone the repo and then checkout the limited-beta-release branch. Then, refer to the Getting Started documentation.

Disclaimer:

  • This is beta software. It has not been not fully tested, and may not be at a level of performance or compatibility of generally available software or services Box offers.
  • Any use of this software is governed by the attached Box SDK Beta Agreement. If you do not accept the terms of the Box SDK Beta Agreement, you may not use this software.
  • This beta software should not be used in live/production environments; it is for development / test only.
  • This beta software will be updated frequently and breaking changes should be expected
  • This limited beta is intended for select Box customers
  • Please send all feedback / questions to: sdks-feedback@box.com

Breaking Changes:

  • For Module methods that returned a collection of objects, changed from returning a PaginationIterator to returning a PagingIterator in a completion.
  • Modules are now automatically instantiated with the BoxClient object and no longer allow the client app to instantiate them
  • Related RetentionPolicy classes no longer allow rawData to be set by the client app
  • UploadPartDescription made private
  • Fixed bug with exponential backoff and changed SDK configuration item "retryAfterTime" to "retryBaseInterval"

New Features and Enhancements:

  • RetentionPolicyModule methods made public
  • Added additional supporting types
  • Improved support for logging to file, allow for custom file path, and fixed some related bugs
  • Improved console logging formatting
  • Updated Sample Apps to use new PagingIterator responses

v3.0.0-rc.2 - Oct 30, 2019

Box iOS Swift SDK Release Candidate

Disclaimer:

  • This is beta software. It has not been not fully tested, and may not be at a level of performance or compatibility of generally available software or services Box offers.
  • Any use of this software is governed by the attached Box SDK Beta Agreement. If you do not accept the terms of the Box SDK Beta Agreement, you may not use this software.
  • This beta software should not be used in live/production environments; it is for development / test only.
  • This beta software will be updated frequently and breaking changes should be expected
  • This limited beta is intended for select Box customers
  • Please send all feedback / questions to: sdks-feedback@box.com

Breaking Changes:

  • Changed SDK errors from customValue enum cases to specific enum cases

New Features and Enhancements:

  • Added Xcode 11 + iOS 13 support to Travis CI

v3.0.0-rc.1 - Oct 19, 2019

Box iOS Swift SDK Release Candidate

Disclaimer:

  • This is beta software. It has not been not fully tested, and may not be at a level of performance or compatibility of generally available software or services Box offers.
  • Any use of this software is governed by the attached Box SDK Beta Agreement. If you do not accept the terms of the Box SDK Beta Agreement, you may not use this software.
  • This beta software should not be used in live/production environments; it is for development / test only.
  • This beta software will be updated frequently and breaking changes should be expected
  • This limited beta is intended for select Box customers
  • Please send all feedback / questions to: sdks-feedback@box.com

Breaking Changes:

  • Changed TaskAssignment.resolutionState from String to new AssignmentState enum type
  • Changed Group.groupType from String to new GroupType enum type
  • Changed Folder.allowedSharedLinkAccessLevels from [String] to new [SharedLinkAccess] enum type
  • Changed File.allowedInviteeRoles from [String] to new [CollaborationRole] enum type
  • Network responses with 4xx or 5xx status codes are now transformed into an API Error
  • CollaborationItem changed from class to enum
  • CommentItem changed from class to enum
  • FolderItem changed from class to enum
  • WebhookItem changed from class to enum
  • TaskItem changed from class to enum
  • JSON decoding errors now emit expected type
  • Public method names changed to a new convention in many of the "module" classes
  • Redesigned error classes and error hierarchy

New Features and Enhancements:

  • Added Xcode 11 support (SDK builds still target iOS 11.0)

  • Removed AlamoFire dependency

  • Added support for Device Pins

  • Added SDK Configuration URL validation

  • Added SDK-level constants rootFolder and currentUser for convenience

  • Added support for Collaboration Whitelist endpoints

  • Added support for Retention Policy endpoints

  • Added support for Tasks endpoints

  • Added support for Webhooks endpoints

  • Added support for Groups and Group Membership endpoints

  • Added support for Legal Holds endpoints

  • Added support for Terms of Service endpoints

  • Added support for Terms of Service User Status endpoints

  • Added support for Watermarking endpoints

  • Added support for Storage Policy endpoints

  • Added support for Metadata Cascade Policy endpoints

  • Added support for User endpoints

  • Added support for Events endpoints

  • Added Error Views in Sample Apps

  • Improved structure and usability of Sample Apps

v3.0.0-alpha.3 - Aug 30, 2019

Box iOS Swift SDK for Limited Beta Release

Disclaimer:

  • This is beta software. It has not been not fully tested, and may not be at a level of performance or compatibility of generally available software or services Box offers.
  • Any use of this software is governed by the attached Box SDK Beta Agreement. If you do not accept the terms of the Box SDK Beta Agreement, you may not use this software.
  • This beta software should not be used in live/production environments; it is for development / test only.
  • This beta software will be updated frequently and breaking changes should be expected
  • This limited beta is intended for select Box customers
  • Please send all feedback / questions to: sdks-feedback@box.com

Breaking Changes:

  • Changed File Entry Container "entries" from optional to not optional

New Features and Enhancements:

  • Added support for Web Links
  • Added support for Trash endpoints
  • Added support for Recent Items
  • Added support for File Version endpoints
  • Added support for Delete File endpoint
  • Added support for Chunked Upload Endpoints
  • Added support for upload preflight check
  • Added support for downloading a representation of a file
  • Added support for custom OAuth2 Callback URL
  • Added KeychainTokenStore for OAuth2SampleApp