Skip to content

Commit 96ec36a

Browse files
prayanshprayansh
authored
update README for beta release (#60)
* update README for beta release * add iPadOS to list of supported platforms * update usage example
1 parent 74839c7 commit 96ec36a

File tree

1 file changed

+37
-317
lines changed

1 file changed

+37
-317
lines changed

‎README.md

Lines changed: 37 additions & 317 deletions
Original file line numberDiff line numberDiff line change
@@ -1,344 +1,63 @@
11
# Analytics-Swift
22

3-
NOTE: This project is currently in the Pilot phase and is covered by Segment's [First Access & Beta Preview Terms](https://segment.com/legal/first-access-beta-preview/). We encourage you
4-
to try out this new library. Please provide feedback via Github issues/PRs, and feel free to submit pull requests. This library will eventually
5-
supplant our `analytics-ios` library, but customers should not use this library for production applications during our Pilot phase.
3+
NOTE: This project is currently in the Beta phase and is covered by Segment's [First Access & Beta Preview Terms](https://segment.com/legal/first-access-beta-preview/). We encourage you
4+
to try out this new library. Please provide feedback via Github issues/PRs, and feel free to submit pull requests.
65

7-
The hassle-free way to add Segment analytics to your Swift app (iOS/tvOS/watchOS/macOS/Linux).
6+
The hassle-free way to add Segment analytics to your Swift app (iOS/tvOS/watchOS/macOS/Linux/iPadOS). Analytics helps you measure your users, product, and business. It unlocks insights into your app's funnel, core business metrics, and whether you have product-market fit.
87

9-
## Table of Contents
10-
- [Installation](#installation)
11-
- [Usage](#usage)
12-
- [Setting up the client](#setting-up-the-client)
13-
- [Client Options](#client-options)
14-
- [Client Methods](#client-methods)
15-
- [track](#track)
16-
- [identify](#identify)
17-
- [screen](#screen)
18-
- [group](#group)
19-
- [add](#add)
20-
- [find](#find)
21-
- [remove](#remove)
22-
- [flush](#flush)
23-
- [Plugin Architecture](#plugin-architecture)
24-
- [Fundamentals](#fundamentals)
25-
- [Advanced Concepts](#advanced-concepts)
26-
- [Contributing](#contributing)
27-
- [Code of Conduct](#code-of-conduct)
28-
- [License](#license)
8+
## How to get started
9+
1. **Collect analytics data** from your app(s).
10+
- The top 200 Segment companies collect data from 5+ source types (web, mobile, server, CRM, etc.).
11+
2. **Send the data to analytics tools** (for example, Google Analytics, Amplitude, Mixpanel).
12+
- Over 250+ Segment companies send data to eight categories of destinations such as analytics tools, warehouses, email marketing and remarketing systems, session recording, and more.
13+
3. **Explore your data** by creating metrics (for example, new signups, retention cohorts, and revenue generation).
14+
- The best Segment companies use retention cohorts to measure product market fit. Netflix has 70% paid retention after 12 months, 30% after 7 years.
2915

30-
## Installation
31-
Add the Swift package as a dependency either via your package.swift, or via Xcode's File->Swift Packages->Add Package Dependency menu item.
16+
[Segment](https://segment.com) collects analytics data and allows you to send it to more than 250 apps (such as Google Analytics, Mixpanel, Optimizely, Facebook Ads, Slack, Sentry) just by flipping a switch. You only need one Segment code snippet, and you can turn integrations on and off at will, with no additional code. [Sign up with Segment today](https://app.segment.com/signup).
3217

33-
`git@github.com:segmentio/analytics-swift.git`
18+
### Why?
19+
1. **Power all your analytics apps with the same data**. Instead of writing code to integrate all of your tools individually, send data to Segment, once.
3420

35-
Once completed, Analytics can be referenced by importing Segment's Analytics package
21+
2. **Install tracking for the last time**. We're the last integration you'll ever need to write. You only need to instrument Segment once. Reduce all of your tracking code and advertising tags into a single set of API calls.
3622

37-
`import Segment`
23+
3. **Send data from anywhere**. Send Segment data from any device, and we'll transform and send it on to any tool.
3824

39-
## Usage
40-
### Setting up the client
41-
The Analytics client will typically be set up at application launch time, such as `applicationDidFinishLaunching`.
25+
4. **Query your data in SQL**. Slice, dice, and analyze your data in detail with Segment SQL. We'll transform and load your customer behavioral data directly from your apps into Amazon Redshift, Google BigQuery, or Postgres. Save weeks of engineering time by not having to invent your own data warehouse and ETL pipeline.
4226

43-
Typically the following call may be all that's required.
44-
45-
```swift
46-
Analytics(configuration: Configuration("<YOUR_WRITE_KEY>"))
47-
```
48-
49-
### Configuration Options
50-
When creating a new client, you can configure it in various ways. Some examples are listed below.
51-
52-
```swift
53-
let config = Configuration(writeKey: "<YOUR_WRITE_KEY>")
54-
.flushAt(3)
55-
.trackApplicationLifecycleEvents(true)
56-
.flushInterval(10)
57-
58-
let analytics = Analytics(configuration: config)
59-
```
60-
61-
| Name | Default | Description |
62-
| ---- | ------- | ----- |
63-
| writeKey | *required* | Your Segment writeKey |
64-
| application | `nil` | application specific object |
65-
| trackApplicationLifecycleEvents | `true` | automatically track Lifecycle events |
66-
| trackDeepLinks | `true` | automatically track deep links |
67-
| flushAt | `20` | count of events at which we flush events |
68-
| flushInterval | `30` (seconds) | interval in seconds at which we flush events
69-
| defaultSettings | `{}` | Settings object that will be used as fallback in case of network failure
70-
| autoAddSegmentDestination | `true` | automatically add SegmentDestination plugin, disable in case you want to add plugins to SegmentDestination
71-
| apiHost | `api.segment.io/v1` | set a default apiHost to which Segment sends event
72-
73-
You may notice that some configuration options such as IDFA collection and automatic screen tracking from our previous library have been removed.
74-
These options have been moved to distinct plugins that can be found in our [Plugin Examples repo](https://github.com/segmentio/analytics-example-plugins/tree/main/plugins/swift).
75-
## Client Methods
76-
77-
### track
78-
The track method is how you record any actions your users perform, along with any properties that describe the action.
79-
80-
Method signatures:
81-
```swift
82-
func track(name: String)
83-
// This signature provides a typed version of properties.
84-
func track<P: Codable>(name: String, properties: P?)
85-
// Generic dictionary for properties
86-
func track(name: String, properties: [String: Any]?)
87-
```
88-
89-
Example usage:
90-
```swift
91-
struct TrackProperties: Codable {
92-
let someValue: String
93-
}
94-
95-
// ...
96-
97-
analytics.track(name: "My Event", TrackProperties(someValue: "Hello"))
98-
99-
analytics.track(name: "Another Event", ["someValue": "Goodbye"])
100-
```
101-
102-
### identify
103-
The identify call lets you tie a user to their actions and record traits about them. This includes a unique user ID and any optional traits you know about them like their email, name, etc. The traits option can include any information you might want to tie to the user, but when using any of the reserved user traits, you should make sure to only use them for their intended meaning.
104-
105-
Method signatures:
106-
```swift
107-
// These signatures provide for a typed version of user traits
108-
func identify<T: Codable>(userId: String, traits: T)
109-
func identify<T: Codable>(traits: T)
110-
func identify(userId: String)
111-
```
112-
113-
Example Usage:
114-
```swift
115-
struct MyTraits: Codable {
116-
let favoriteColor: String
117-
}
118-
119-
// ...
120-
121-
analytics.identify("someone@segment.com", MyTraits(favoriteColor: "fuscia"))
122-
```
123-
124-
### screen
125-
The screen call lets you record whenever a user sees a screen in your mobile app, along with any properties about the screen.
126-
127-
Method signatures:
128-
```swift
129-
func screen(title: String, category: String? = nil)
130-
func screen<P: Codable>(title: String, category: String? = nil, properties: P?)
131-
```
132-
133-
Example Usage:
134-
```swift
135-
analytics.screen(title: "SomeScreen")
136-
```
137-
138-
You can enable automatic screen tracking by using the [example plugin](https://github.com/segmentio/analytics-example-plugins/blob/main/plugins/swift/UIKitScreenTracking.swift).
139-
140-
Once the plugin has been added to your project add it to your Analytics instance:
141-
```swift
142-
analytics.add(plugin: UIKitScreenTracking()
143-
```
144-
145-
### group
146-
The group API call is how you associate an individual user with a group—be it a company, organization, account, project, team or whatever other crazy name you came up with for the same concept! This includes a unique group ID and any optional group traits you know about them like the company name industry, number of employees, etc. The traits option can include any information you might want to tie to the group, but when using any of the reserved group traits, you should make sure to only use them for their intended meaning.
147-
Method signatures:
148-
```swift
149-
func group(groupId: String)
150-
func group<T: Codable>(groupId: String, traits: T?)
151-
```
152-
153-
Example Usage:
154-
```swift
155-
struct MyTraits: Codable {
156-
let username: String
157-
let email: String
158-
let plan: String
159-
}
160-
161-
// ...
162-
163-
analytics.group("user-123", MyTraits(
164-
username: "MisterWhiskers",
165-
email: "hello@test.com",
166-
plan: "premium"))
167-
```
168-
169-
### add
170-
Add API allows you to add a plugin to the analytics timeline. It will return the plugin instance in
171-
case you wish to store it for access later.
172-
173-
Method signature:
174-
```swift
175-
@discardableResult func add(plugin: Plugin) -> Plugin
176-
```
177-
178-
Example Usage:
179-
```swift
180-
analytics.add(plugin: UIKitScreenTracking())
181-
```
182-
183-
### find
184-
Find a registered plugin from the analytics timeline. It will return the first plugin
185-
of the specified type.
186-
187-
Method signature:
188-
```swift
189-
func find<T: Plugin>(pluginType: T.Type) -> T?
190-
```
191-
192-
Example Usage:
193-
```swift
194-
let plugin = analytics.find(pluginType: SomePlugin.self)
195-
```
196-
197-
### remove
198-
Remove a registered plugin from the analytics timeline.
199-
200-
Method signature:
201-
```swift
202-
func remove(plugin: Plugin)
203-
```
204-
205-
Example Usage:
206-
```swift
207-
analytics.remove(plugin: somePlugin)
208-
```
209-
210-
### flush
211-
Flushes the current queue of events.
212-
213-
Example Usage:
214-
```swift
215-
analytics.flush()
216-
```
217-
218-
## Plugin Architecture
219-
Our new plugin architecture enables you to modify/augment how the analytics client works completely. From modifying event payloads to changing analytics functionality, plugins are the easiest way to get things done.
220-
Plugins are run through a timeline, which executes plugins in order of insertion based on their types.
221-
We have the following [types]
222-
- `before` _Executed before event processing begins_
223-
- `enrichment` _Executed as the first level of event processing_
224-
- `destination` _Executed as events begin to pass off to destinations_
225-
- `after` _Executed after all event processing is completed. This can be used to perform cleanup operations, etc_
226-
- `utility` _Executed only when called manually, such as Logging_
227-
228-
### Fundamentals
229-
We have 3 types of basic plugins that you can use as a foundation for modifying functionality
230-
231-
- `Plugin`
232-
The most trivial plugin interface that will act on any event payload going through the timeline.
233-
For example if you wanted to add something to the context object of any event payload as an enrichment.
234-
```swift
235-
class SomePlugin: Plugin {
236-
let type: PluginType = .enrichment
237-
let analytics: Analytics
238-
239-
init() {
240-
}
241-
242-
override fun execute(event: BaseEvent): BaseEvent? {
243-
var workingEvent = event
244-
if var context = workingEvent?.context?.dictionaryValue {
245-
context[keyPath: "foo.bar"] = 12
246-
workingEvent?.context = try? JSON(context)
247-
}
248-
return workingEvent
249-
}
250-
}
251-
```
252-
253-
- `EventPlugin`
254-
A plugin interface that will act only on specific event types. You can choose the event types by only overriding the event functions you want.
255-
For example if you only wanted to act on `track` & `identify` events
256-
```swift
257-
class SomePlugin: EventPlugin {
258-
let type: PluginType = .enrichment
259-
let analytics: Analytics
260-
261-
init() {
262-
}
263-
264-
func identify(event: IdentifyEvent) -> IdentifyEvent? {
265-
// code to modify identify event
266-
return event
267-
}
268-
269-
func track(event: TrackEvent) -> TrackEvent? {
270-
// code to modify track event
271-
return event
272-
}
273-
}
274-
```
275-
276-
- `DestinationPlugin`
277-
A plugin interface most commonly used for device-mode destinations. This plugin contains an internal timeline that follows the same process as the analytics timeline,
278-
allowing you to modify/augment how events reach the particular destination.
279-
For example if you wanted to implement a device mode destination plugin for AppsFlyer
280-
```swift
281-
internal struct AppsFlyerSettings: Codable {
282-
let appsFlyerDevKey: String
283-
let appleAppID: String
284-
let trackAttributionData: Bool?
285-
}
286-
287-
@objc
288-
class AppsFlyerDestination: UIResponder, DestinationPlugin, UserActivities, RemoteNotifications {
289-
290-
let timeline: Timeline = Timeline()
291-
let type: PluginType = .destination
292-
let key: String = "AppsFlyer"
293-
var analytics: Analytics?
294-
295-
internal var settings: AppsFlyerSettings? = nil
296-
297-
init() {
27+
For example, you can capture data on any app:
28+
```swift
29+
struct TrackProperties: Codable {
30+
let price: Double
29831
}
299-
300-
public func update(settings: Settings, type: UpdateType) {
301-
if type == .initial {
302-
// AppsFlyerLib is a singleton, we only want to set it up once.
303-
guard let settings: AppsFlyerSettings = settings.integrationSettings(key: self.name) else {return}
304-
self.settings = settings
305-
306-
AppsFlyerLib.shared().appsFlyerDevKey = settings.appsFlyerDevKey
307-
AppsFlyerLib.shared().appleAppID = settings.appleAppID
308-
AppsFlyerLib.shared().isDebug = true
309-
AppsFlyerLib.shared().deepLinkDelegate = self
31032

311-
analytics?.track(name: "AppsFlyer Loaded")
312-
}
313-
314-
// additional update logic
315-
}
33+
// ...
31634

317-
// ...
35+
analytics.track(name: "Order Completed", properties: TrackProperties(price: 99.84))
36+
```
37+
Then, query the resulting data in SQL:
38+
```sql
39+
select * from app.order_completed
40+
order by price desc
41+
```
31842

319-
analytics.add(plugin: AppsFlyerPlugin(name: "AppsFlyer"))
320-
analytics.track("AppsFlyer Event")
321-
```
43+
## Documentation
44+
45+
You can find usage documentation at [https://segment.com/docs/sources/mobile/swift-ios/](https://segment.com/docs/sources/mobile/swift-ios/).
32246

323-
### Advanced concepts
324-
- `update(settings:type:)`
325-
Use this function to react to any settings updates. This will be implicitly called when settings are updated.
326-
- OS Lifecycle hooks
327-
Plugins can also hook into lifecycle events by conforming to the platform appropriate protocol. These functions will get called implicitly as the lifecycle events are processed.
328-
`iOSLifecycleEvents`
329-
`macOSLifecycleEvents`
330-
`watchOSLifecycleEvents`
331-
`LinuxLifecycleEvents`
33247
## Contributing
33348

33449
See the [contributing guide](CONTRIBUTING.md) to learn how to contribute to the repository and the development workflow.
33550

51+
## Integrating with Segment
52+
53+
Interested in integrating your service with us? Check out our [Partners page](https://segment.com/partners/) for more details.
54+
33655
## Code of Conduct
33756

33857
Before contributing, please also see our [code of conduct](CODE_OF_CONDUCT.md).
33958

34059
## License
341-
60+
```
34261
MIT License
34362

34463
Copyright (c) 2021 Segment
@@ -360,3 +79,4 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
36079
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
36180
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
36281
SOFTWARE.
82+
```

0 commit comments

Comments
 (0)