Skip to content
This repository was archived by the owner on Feb 15, 2022. It is now read-only.

README 1.0 Updates #197

Merged
merged 6 commits into from
Jan 27, 2017
Merged

README 1.0 Updates #197

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
533f7b6
Updates to README for 1.0 release
mliberatore Jan 13, 2017
0f33a48
Adds Swift version requirements and note about 2.3
mliberatore Jan 13, 2017
1a611d8
Fixes small typo ("take peek" → "take a peek")
mliberatore Jan 13, 2017
6cd949d
Merge remote-tracking branch 'origin/develop' into readme-1.0-updates
bcapps Jan 20, 2017
7d788c8
Adds buddybuild build status, CocoaPods, and Carthage badges
bcapps Jan 20, 2017
2721180
Merge pull request #201 from Lickability/readme-build-status-badge
mliberatore Jan 20, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 21 additions & 15 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,9 @@
![PinpointKit Logo](Assets/logo.png)

[![BuddyBuild](https://dashboard.buddybuild.com/api/statusImage?appID=588239a8711a3f0100b86836&branch=master&build=latest)](https://dashboard.buddybuild.com/apps/588239a8711a3f0100b86836/build/latest?branch=master)
[![CocoaPods Compatible](https://img.shields.io/cocoapods/v/PinpointKit.svg)](https://img.shields.io/cocoapods/v/PinpointKit.svg)
[![Carthage compatible](https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat)](https://github.com/Carthage/Carthage)

**PinpointKit** is an open-source iOS library in Swift that lets your testers and users send feedback with annotated screenshots and logs using a simple gesture.

![Screenshots](Assets/screenshots.png)
Expand Down Expand Up @@ -37,8 +41,10 @@

* iOS 9.0+
* Xcode 8.0+
* Swift 3.0
* Looking for a Swift 2.3 version? See the [README](https://github.com/Lickability/PinpointKit/blob/swift-2.3/README.md) on the [`swift-2.3`](https://github.com/Lickability/PinpointKit/tree/swift-2.3) branch.

> **Note:** [`ScreenshotDetector`](https://github.com/Lickability/PinpointKit/blob/develop/PinpointKit/PinpointKit/Sources/ScreenshotDetector/ScreenshotDetector.swift) depends on the `Photos` framework to access the user’s photo library. This requires you to add an entry for the [`NSPhotoLibraryUsageDescription`](https://developer.apple.com/library/content/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html#//apple_ref/doc/uid/TP40009251-SW17) key in your `Info.plist` file describing your app’s use of the user’s photo library. As of iOS 10, failure to provide a value for this key could cause your submission to the App Store to be rejected by Apple, or cause your app to exit upon attempting to access the user’s photo library. [`ScreenshotDetector`](https://github.com/Lickability/PinpointKit/blob/develop/PinpointKit/PinpointKit/Sources/ScreenshotDetector/ScreenshotDetector.swift) is excluded by default when installing via Cocoapods, but is included otherwise.
> **Note:** [`ScreenshotDetector`](https://github.com/Lickability/PinpointKit/blob/master/PinpointKit/PinpointKit/Sources/ScreenshotDetector/ScreenshotDetector.swift) depends on the `Photos` framework to access the user’s photo library. This requires you to add an entry for the [`NSPhotoLibraryUsageDescription`](https://developer.apple.com/library/content/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html#//apple_ref/doc/uid/TP40009251-SW17) key in your `Info.plist` file describing your app’s use of the user’s photo library. As of iOS 10, failure to provide a value for this key could cause your submission to the App Store to be rejected by Apple, or cause your app to exit upon attempting to access the user’s photo library. [`ScreenshotDetector`](https://github.com/Lickability/PinpointKit/blob/master/PinpointKit/PinpointKit/Sources/ScreenshotDetector/ScreenshotDetector.swift) is excluded by default when installing via Cocoapods, but is included otherwise.

## Installation

Expand All @@ -60,7 +66,7 @@ platform :ios, '9.0'
use_frameworks!

target 'YOUR_TARGET_NAME' do
pod 'PinpointKit', :git => 'https://github.com/Lickability/PinpointKit.git', :branch => 'develop'
pod 'PinpointKit', '~> 1.0'
end

```
Expand All @@ -71,10 +77,10 @@ Then, run the following command:
$ pod install
```

We also offer a convenience class, [`ScreenshotDetector`](https://github.com/Lickability/PinpointKit/blob/develop/PinpointKit/PinpointKit/Sources/ScreenshotDetector/ScreenshotDetector.swift) that is available via the `ScreenshotDetector` subspec. This class provides delegate callbacks when the user takes a screenshot while using your app. Please see the [Requirements](#requirements) section regarding inclusion of [`ScreenshotDetector`](https://github.com/Lickability/PinpointKit/blob/develop/PinpointKit/PinpointKit/Sources/ScreenshotDetector/ScreenshotDetector.swift). You can add this to your project by adding the following line in your `Podfile`, in addition to the one for `PinpointKit` above:
We also offer a convenience class, [`ScreenshotDetector`](https://github.com/Lickability/PinpointKit/blob/master/PinpointKit/PinpointKit/Sources/ScreenshotDetector/ScreenshotDetector.swift) that is available via the `ScreenshotDetector` subspec. This class provides delegate callbacks when the user takes a screenshot while using your app. Please see the [Requirements](#requirements) section regarding inclusion of [`ScreenshotDetector`](https://github.com/Lickability/PinpointKit/blob/master/PinpointKit/PinpointKit/Sources/ScreenshotDetector/ScreenshotDetector.swift). You can add this to your project by adding the following line in your `Podfile`, in addition to the one for `PinpointKit` above:

```ruby
pod 'PinpointKit/ScreenshotDetector', :git => 'https://github.com/Lickability/PinpointKit.git', :branch => 'develop'
pod 'PinpointKit/ScreenshotDetector', '~> 1.0'
```

### Carthage
Expand All @@ -91,7 +97,7 @@ $ brew install carthage
To integrate PinpointKit into your Xcode project using Carthage, specify it in your `Cartfile`:

```ogdl
github "Lickability/PinpointKit" "develop"
github "Lickability/PinpointKit" ~> 1.0
```

- Run `carthage update` to build the framework.
Expand All @@ -114,7 +120,7 @@ $ git init
- Add PinpointKit as a git [submodule](http://git-scm.com/docs/git-submodule) by running the following command:

```bash
$ git submodule add -b develop https://github.com/Lickability/PinpointKit.git
$ git submodule add -b master https://github.com/Lickability/PinpointKit.git
```

- Open the new `PinpointKit/PinpointKit` folder, and drag the `PinpointKit.xcodeproj` into the Project Navigator of your application’s Xcode project.
Expand All @@ -136,18 +142,18 @@ The `PinpointKit.framework` is automatically added as a target dependency, linke

Once PinpointKit is installed, it’s simple to use.

Initialize an instance of [`PinpointKit`](https://github.com/Lickability/PinpointKit/blob/master/PinpointKit/PinpointKit/Sources/PinpointKit.swift), specifying an array of feedback recipients used to pre-populate email addresses to which feedback can be sent:
Initialize an instance of [`PinpointKit`](https://github.com/Lickability/PinpointKit/blob/master/PinpointKit/PinpointKit/Sources/Core/PinpointKit.swift), specifying an array of feedback recipients used to pre-populate email addresses to which feedback can be sent:

```swift
let pinpointKit = PinpointKit(feedbackRecipients: ["[email protected]"])
```

To display a feedback view controller, add the following code where you want the feedback to display, passing the view controller from which [`PinpointKit`](https://github.com/Lickability/PinpointKit/blob/master/PinpointKit/PinpointKit/Sources/PinpointKit.swift) should present:
To display a feedback view controller, add the following code where you want the feedback to display, passing the view controller from which [`PinpointKit`](https://github.com/Lickability/PinpointKit/blob/master/PinpointKit/PinpointKit/Sources/Core/PinpointKit.swift) should present:

```swift
pinpointKit.show(from: viewController)
```
> **Note:** Be sure to keep a strong reference to your instance of [`PinpointKit`](https://github.com/Lickability/PinpointKit/blob/master/PinpointKit/PinpointKit/Sources/PinpointKit.swift) for the duration of its use.
> **Note:** Be sure to keep a strong reference to your instance of [`PinpointKit`](https://github.com/Lickability/PinpointKit/blob/master/PinpointKit/PinpointKit/Sources/Core/PinpointKit.swift) for the duration of its use.

If you want to have the feedback view display from a shake gesture, simply add the following to your application delegate, replacing `["[email protected]"]` with your array of email recipients and `AppDelegate` with your application delegate’s name:

Expand All @@ -156,19 +162,19 @@ private static let pinpointKit = PinpointKit(feedbackRecipients: ["feedback@exam
var window: UIWindow? = ShakeDetectingWindow(frame: UIScreen.main.bounds, delegate: AppDelegate.pinpointKit)
```

If you don’t want to use [`PinpointKit`](https://github.com/Lickability/PinpointKit/blob/master/PinpointKit/PinpointKit/Sources/PinpointKit.swift)’s default configuration, you can specify both [`Configuration`](https://github.com/Lickability/PinpointKit/blob/master/PinpointKit/PinpointKit/Sources/Configuration.swift) and [`PinpointKitDelegate`](https://github.com/Lickability/PinpointKit/blob/master/PinpointKit/PinpointKit/Sources/PinpointKit.swift) instances on initialization of [`PinpointKit`](https://github.com/Lickability/PinpointKit/blob/master/PinpointKit/PinpointKit/Sources/PinpointKit.swift).
If you don’t want to use [`PinpointKit`](https://github.com/Lickability/PinpointKit/blob/master/PinpointKit/PinpointKit/Sources/Core/PinpointKit.swift)’s default configuration, you can specify both [`Configuration`](https://github.com/Lickability/PinpointKit/blob/master/PinpointKit/PinpointKit/Sources/Core/Configuration.swift) and [`PinpointKitDelegate`](https://github.com/Lickability/PinpointKit/blob/master/PinpointKit/PinpointKit/Sources/Core/PinpointKit.swift) instances on initialization of [`PinpointKit`](https://github.com/Lickability/PinpointKit/blob/master/PinpointKit/PinpointKit/Sources/Core/PinpointKit.swift).

The [`Configuration`](https://github.com/Lickability/PinpointKit/blob/master/PinpointKit/PinpointKit/Sources/Configuration.swift) struct allows you to specify how the feedback view looks and behaves, while the [`PinpointKitDelegate`](https://github.com/Lickability/PinpointKit/blob/master/PinpointKit/PinpointKit/Sources/PinpointKit.swift) instance provides hooks into the state of the feedback being sent.
The [`Configuration`](https://github.com/Lickability/PinpointKit/blob/master/PinpointKit/PinpointKit/Sources/Core/Configuration.swift) struct allows you to specify how the feedback view looks and behaves, while the [`PinpointKitDelegate`](https://github.com/Lickability/PinpointKit/blob/master/PinpointKit/PinpointKit/Sources/Core/PinpointKit.swift) instance provides hooks into the state of the feedback being sent.

## Customization

PinpointKit uses a protocol-oriented architecture which allows almost everything to be customized. Here are some examples of what’s possible:

* Implement a `JIRASender` that conforms to [`Sender`](https://github.com/Lickability/PinpointKit/blob/master/PinpointKit/PinpointKit/Sources/Sender.swift), allowing users to send feedback directly into your bug tracker.
* Supply your own console log collector that aggregates messages from your third-party logging framework of choice by conforming to [`LogCollector`](https://github.com/Lickability/PinpointKit/blob/master/PinpointKit/PinpointKit/Sources/LogCollector.swift)
* Change how logs are viewed by creating your own view controller conforming to [`LogViewer`](https://github.com/Lickability/PinpointKit/blob/master/PinpointKit/PinpointKit/Sources/LogViewer.swift).
* Implement a `JIRASender` that conforms to [`Sender`](https://github.com/Lickability/PinpointKit/blob/master/PinpointKit/PinpointKit/Sources/Core/Sender.swift), allowing users to send feedback directly into your bug tracker.
* Supply your own console log collector that aggregates messages from your third-party logging framework of choice by conforming to [`LogCollector`](https://github.com/Lickability/PinpointKit/blob/master/PinpointKit/PinpointKit/Sources/Core/LogCollector.swift)
* Change how logs are viewed by creating your own view controller conforming to [`LogViewer`](https://github.com/Lickability/PinpointKit/blob/master/PinpointKit/PinpointKit/Sources/Core/LogViewer.swift).

For more information on what you can customize, take a peek the documentation of [`Configuration`](https://github.com/Lickability/PinpointKit/blob/master/PinpointKit/PinpointKit/Sources/Configuration.swift).
For more information on what you can customize, take a peek at the documentation of [`Configuration`](https://github.com/Lickability/PinpointKit/blob/master/PinpointKit/PinpointKit/Sources/Core/Configuration.swift).

## License

Expand Down