/DeviceKit

DeviceKit is a value-type replacement of UIDevice.

Primary LanguageSwiftMIT LicenseMIT

GitHub license CocoaPods Compatible Carthage Compatible codecov CocoaPods Maintainability Platform

Branch Build Status Versions
master Build Status ≥ 2.0
Swift 4 - 4.2 Build Status ≥ 1.3 < 1.13
Swift 3 Build Status ≥ 1.0 < 1.3
Swift 2.3 Build Status < 1.0

DeviceKit is a value-type replacement of UIDevice.

Changelog 2.0

Here you find an overview about all the latest features, bugfixes and breaking changes shipped with version 2.0 which was released on 10th April 2019.

Breaking changes

  • The original Device() constructor has been made private in favour of using Device.current to match UIDevice.current.
  • The enum values for the iPhone Xs, iPhone Xs Max and iPhone Xʀ have been renamed to be .iPhoneXS, .iPhoneXSMax and .iPhoneXR to match proper formatting.
  • .description for the iPhone Xs, iPhone Xs Max and iPhone Xʀ have been changed to contain small caps formatting for the s and the ʀ part.
  • .description for the iPad 5 and iPad 6 have been changed to the proper names; iPad (5th generation) and iPad (6th generation).
  • .name, .systemName, .systemVersion, .model, .localizedModel, .batteryState and .batteryLevel will now all return nil when you try to get its value when the device you are getting it from isn't the current one. (eg. Device.iPad6.name while running on iPad 5)

New features

  • Updated to Swift 5!
  • New .allDevicesWithRoundedDisplayCorners and .hasRoundedDisplayCorners values to check if a device has rounded display corners. (eg. iPhone Xs and iPad Pro (3rd generation))
  • new .allDevicesWithSensorHousing and .hasSensorHousing values to check if a device has a screen cutout for the sensor housing. (eg. iPhone Xs)

Bugfixes

  • .isPad and .isPhone are now giving correct outputs again.

Features

  • Equatable
  • Device identification
  • Device family detection
  • Device group detection
  • Simulator detection
  • Battery state
  • Battery level
  • Various device metrics (e.g. screen size, screen ratio, PPI)
  • Low Power Mode detection
  • Guided Access Session detection
  • Screen brightness
  • Display Zoom detection
  • Detect available sensors (Touch ID, Face ID)
  • Detect available disk space
  • Apple Pencil support detection

Requirements

  • iOS 8.0+ (linking against iOS 9.3 required)
  • tvOS 9.0+ (linking against tvOS 9.2 required)
  • watchOS 2.0+

Installation

DeviceKit can be installed in various ways.

CocoaPods

Swift 5

pod 'DeviceKit', '~> 2.0'

Swift 4.0 - Swift 4.2

pod 'DeviceKit', '~> 1.3'

Swift 3

pod 'DeviceKit', '~> 1.2.3'

Swift 2.3 (Unsupported)

pod 'DeviceKit', :git => 'https://github.com/devicekit/DeviceKit.git', :branch => 'swift-2.3-unsupported'

Carthage

Swift 5

github "devicekit/DeviceKit" ~> 2.0

Swift 4.0 - Swift 4.2

github "devicekit/DeviceKit" ~> 1.3

Swift 3

github "devicekit/DeviceKit" ~> 1.2.3

Swift 2.3 (Unsupported)

github "devicekit/DeviceKit" "swift-2.3-unsupported"

Manually

To install it manually, drag the DeviceKit project into your app project in Xcode. Or add it as a git submodule by running:

$ git submodule add https://github.com/devicekit/DeviceKit.git

Usage

First make sure to import the framework:

import DeviceKit

Here are some usage examples. All devices are also available as simulators:

.iPhone6 => .simulator(.iPhone6)
.iPhone6s => .simulator(.iPhone6s)

You can try these examples in Playground.

Note:

To try DeviceKit in the playground, open the DeviceKit.xcworkspace and build DeviceKit.framework for any simulator first by selecting "DeviceKit" as your current scheme.

Get the Device You're Running On

let device = Device.current

print(device)     // prints, for example, "iPhone 6 Plus"

if device == .iPhone6Plus {
  // Do something
} else {
  // Do something else
}

Get the Device Family

let device = Device.current
if device.isPod {
  // iPods (real or simulator)
} else if device.isPhone {
  // iPhone (real or simulator)
} else if device.isPad {
  // iPad (real or simulator)
}

Check If Running on Simulator

let device = Device.current
if device.isSimulator {
  // Running on one of the simulators(iPod/iPhone/iPad)
  // Skip doing something irrelevant for Simulator
} 

Get the Simulator Device

let device = Device.current
switch device {
case .simulator(.iPhone6s): break // You're running on the iPhone 6s simulator
case .simulator(.iPadAir2): break // You're running on the iPad Air 2 simulator
default: break
}

Make Sure the Device Is Contained in a Preconfigured Group

let groupOfAllowedDevices: [Device] = [.iPhone6, .iPhone6Plus, .iPhone6s, .iPhone6sPlus, .simulator(.iPhone6), .simulator(.iPhone6Plus),.simulator(.iPhone6s),.simulator(.iPhone6sPlus).simulator(.iPhone8),.simulator(.iPhone8Plus),.simulator(.iPhoneX),.simulator(.iPhoneXS),.simulator(.iPhoneXSMax),.simulator(.iPhoneXR)]

let device = Device.current
 
if device.isOneOf(groupOfAllowedDevices) {
  // Do your action
}

Get the Current Battery State

Note:

To get the current battery state we need to set UIDevice.current.isBatteryMonitoringEnabled to true. To avoid any issues with your code, we read the current setting and reset it to what it was before when we're done.

if device.batteryState == .full || device.batteryState >= .charging(75) {
  print("Your battery is happy! 😊")
}

Get the Current Battery Level

if device.batteryLevel >= 50 {
  install_iOS()
} else {
  showError()
}

Get Low Power mode status

if device.batteryState.lowPowerMode {
  print("Low Power mode is enabled! 🔋")
} else {
  print("Low Power mode is disabled! 😊")
}

Check if a Guided Access session is currently active

if device.isGuidedAccessSessionActive {
  print("Guided Access session is currently active")
} else {
  print("No Guided Access session is currently active")
}

Get Screen Brightness

if device.screenBrightness > 50 {
  print("Take care of your eyes!")
}

Get Available Disk Space

if Device.volumeAvailableCapacityForOpportunisticUsage ?? 0 > Int64(1_000_000) {
  // download that nice-to-have huge file
}

if Device.volumeAvailableCapacityForImportantUsage ?? 0 > Int64(1_000) {
  // download that file you really need
}

Source of Information

All model identifiers are taken from the following website: https://www.theiphonewiki.com/wiki/Models or extracted from the simulator app bundled with Xcode.

Contributing

If you have the need for a specific feature that you want implemented or if you experienced a bug, please open an issue. If you extended the functionality of DeviceKit yourself and want others to use it too, please submit a pull request.

Contributors

The complete list of people who contributed to this project is available here. DeviceKit wouldn't be what it is without you! Thank you very much! 🙏