Skip to content

Commit 33df0f3

Browse files
HazATHazAT
authored
feat: Adding new docs for sentry-cocoa 5.x (#1551)
* feat: Adding new docs for sentry-cocoa 5.x * feat: Usage updates * fix: Build error * fix: Snapshot * ref: Remove podspec repo * ref: Add robots: noindex to old docs * ref: CodeReview
1 parent b47e82f commit 33df0f3

File tree

23 files changed

+408
-13
lines changed

23 files changed

+408
-13
lines changed

‎__tests__/__snapshots__/documentation.js.snap

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -300,6 +300,9 @@ Array [
300300
"performance/performance-glossary/index.html",
301301
"platforms/android/index.html",
302302
"platforms/android/migrate/index.html",
303+
"platforms/cocoa/dsym/index.html",
304+
"platforms/cocoa/index.html",
305+
"platforms/cocoa/usage/index.html",
303306
"platforms/dotnet/aspnetcore/index.html",
304307
"platforms/dotnet/entityframework/index.html",
305308
"platforms/dotnet/index.html",

‎src/_data/platforms.yml

Lines changed: 5 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -311,13 +311,10 @@
311311
support_level: production
312312
type: language
313313
name: Swift
314-
doc_link: /clients/cocoa/
314+
doc_link: /platforms/cocoa/
315315
wizard_parent: cocoa
316316
wizard:
317-
- _documentation/clients/cocoa/index.md
318-
- _documentation/clients/cocoa/dsym.md
319-
version: 4.1.0
320-
version_key: SENTRY_COCOA_TAG
317+
- _documentation/platforms/cocoa/index.md
321318
-
322319
slug: browser
323320
support_level: production
@@ -454,13 +451,10 @@
454451
support_level: production
455452
type: language
456453
name: Objective-C
457-
doc_link: /clients/cocoa/
454+
doc_link: /platforms/cocoa/
458455
wizard_parent: cocoa
459-
wizard:
460-
- _documentation/clients/cocoa/index.md
461-
- _documentation/clients/cocoa/dsym.md
462-
version: 4.1.0
463-
version_key: SENTRY_COCOA_TAG
456+
wizard:
457+
- _documentation/platforms/cocoa/index.md
464458
-
465459
slug: csharp
466460
support_level: production

‎src/collections/_documentation/clients/cocoa/advanced.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
---
22
title: 'Advanced Usage'
3+
robots: noindex
34
---
45

56
## Capturing uncaught exceptions on macOS

‎src/collections/_documentation/clients/cocoa/dsym.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
---
22
title: 'Uploading Debug Symbols'
3+
robots: noindex
34
---
45

56
A dSYM upload is required for Sentry to symoblicate your crash logs for viewing. The symoblication process unscrambles Apple’s crash logs to reveal the function, variables, file names, and line numbers of the crash. The dSYM file can be uploaded through the [sentry-cli](https://github.com/getsentry/sentry-cli) tool or through a [Fastlane](https://fastlane.tools/) action.

‎src/collections/_documentation/clients/cocoa/index.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
---
22
title: Cocoa
3-
sidebar_relocation: platforms
3+
robots: noindex
44
---
55

6-
This is the documentation for our official clients for Cocoa (Swift and Objective-C). Starting with version `3.0.0` we’ve switched our internal code from Swift to Objective-C to maximize compatibility. Also we trimmed the public API of our sdk to a minimum. Some of the lesser used features that were present before are gone now, check out [Migration Guide]({%- link _documentation/clients/cocoa/migration.md -%}#migration) or [Advanced Usage]({%- link _documentation/clients/cocoa/advanced.md -%}#advanced) for details.
6+
This is the documentation for our official clients for Cocoa (Swift and Objective-C). Starting with version `3.0.0` we’ve switched our internal code from Swift to Objective-C to maximize compatibility. Also we trimmed the public API of our SDK to a minimum. Check out [Migration Guide]({%- link _documentation/clients/cocoa/migration.md -%}#migration) or [Advanced Usage]({%- link _documentation/clients/cocoa/advanced.md -%}#advanced) for details.
77

88
## Getting Started
99
Getting started with Sentry is a three step process:

‎src/collections/_documentation/clients/cocoa/migration.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
---
22
title: 'Migration Guide'
3+
robots: noindex
34
---
45

56
## Upgrade from 2.x.x to 3.x.x {#upgrade-from-2-x-x-to-3-0-x}

‎src/collections/_documentation/platforms/cocoa/captureMessage/objc.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
```objc
2+
[SentrySDK captureMessage:@"My first test message"];
3+
```

‎src/collections/_documentation/platforms/cocoa/captureMessage/swift.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
```swift
2+
SentrySDK.capture(message: "My first test message")
3+
```

‎src/collections/_documentation/platforms/cocoa/configureScope/objc.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
```objc
2+
[SentrySDK configureScope:^(SentryScope * _Nonnull scope) {
3+
[scope setEnvironment:@"debug"];
4+
[scope setTagValue:@"objc" forKey:@"langauge"];
5+
[scope setExtraValue:[NSString stringWithFormat:@"%@", self] forKey:@"currentViewController"];
6+
}];
7+
```

‎src/collections/_documentation/platforms/cocoa/configureScope/swift.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
```swift
2+
SentrySDK.configureScope { (scope) in
3+
scope.setEnvironment("debug")
4+
scope.setTag(value: "swift", key: "language")
5+
scope.setExtra(value: String(describing: self), key: "currentViewController")
6+
}
7+
```

‎src/collections/_documentation/platforms/cocoa/crash/objc.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
```objc
2+
[SentrySDK crash];
3+
```

‎src/collections/_documentation/platforms/cocoa/crash/swift.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
```swift
2+
SentrySDK.crash()
3+
```

‎src/collections/_documentation/platforms/cocoa/dsym.md

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
---
2+
title: 'Uploading Debug Symbols'
3+
---
4+
5+
Sentry requires a dSYM upload to symbolicate your crash logs. The symbolication process unscrambles Apple’s crash logs to reveal the function, file names, and line numbers of the crash. Upload the dSYM file using either [sentry-cli](https://github.com/getsentry/sentry-cli) or the [Fastlane](https://fastlane.tools/) action.
6+
7+
## With Bitcode {#dsym-with-bitcode}
8+
9+
If [Bitcode](https://developer.apple.com/library/ios/documentation/IDEs/Conceptual/AppDistributionGuide/AppThinning/AppThinning.html#//apple_ref/doc/uid/TP40012582-CH35-SW2) **is enabled** in your project, you will have to upload the dSYM to Sentry **after** it has finished processing in iTunesConnect. We also recommend using the latest Xcode version for submitting your build. The dSYM can be downloaded either with [Fastlane](#bitcode-fastlane) or with [sentry-cli](#bitcode-sentrycli).
10+
11+
### Using Fastlane {#bitcode-fastlane}
12+
13+
Use the [Fastlane](https://github.com/fastlane/fastlane) action, _download_dsyms_, to download the dSYMs from iTunesConnect and upload to Sentry. The dSYM won’t be generated until **after** the app is done processing on iTunesConnect so this should be run in its own lane.
14+
15+
```ruby
16+
lane :upload_symbols do
17+
download_dsyms # this is the important part
18+
upload_symbols_to_sentry(
19+
auth_token: 'YOUR_AUTH_TOKEN',
20+
org_slug: '___ORG_NAME___',
21+
project_slug: '___PROJECT_NAME___',
22+
)
23+
end
24+
```
25+
26+
{% capture __alert_content -%}
27+
By default fastlane will connect to sentry.io. For on-prem you need to provide the _api_host_ parameter to instruct the tool to connect to your server:
28+
29+
```
30+
api_host: 'https://mysentry.invalid/'
31+
```
32+
{%- endcapture -%}
33+
{%- include components/alert.html
34+
title="On Prem"
35+
content=__alert_content
36+
%}
37+
38+
### Using `sentry-cli` {#bitcode-sentrycli}
39+
40+
Download the dSYM from iTunesConnect. After that, you can upload the dSYM using [sentry-cli](https://github.com/getsentry/sentry-cli/releases).
41+
42+
1. Open Xcode Organizer, go to your app, and click “Download dSYMs...”
43+
2. Login to iTunes Connect, go to your app, go to “Activity", click the build number to go into the detail page, and click “Download dSYM”
44+
45+
Afterwards manually upload the symbols with _sentry-cli_:
46+
47+
```bash
48+
sentry-cli --auth-token YOUR_AUTH_TOKEN upload-dif --org ___ORG_NAME___ --project ___PROJECT_NAME___ PATH_TO_DSYMS
49+
```
50+
51+
{% capture __alert_content -%}
52+
By default sentry-cli will connect to sentry.io. For on-prem you need to export the _SENTRY_URL_ environment variable to instruct the tool to connect to your server:
53+
54+
```bash
55+
export SENTRY_URL=https://mysentry.invalid/
56+
```
57+
{%- endcapture -%}
58+
{%- include components/alert.html
59+
title="On Prem"
60+
content=__alert_content
61+
%}
62+
63+
## Without Bitcode {#dsym-without-bitcode}
64+
65+
When not using Bitcode you can directly upload the symbols to Sentry as part of your build.
66+
67+
### Using Fastlane
68+
69+
If you are already using Fastlane you can use it in this situation as well:
70+
71+
```ruby
72+
lane :build do
73+
gym # building your app
74+
upload_symbols_to_sentry(
75+
auth_token: 'YOUR_AUTH_TOKEN',
76+
org_slug: '___ORG_NAME___',
77+
project_slug: '___PROJECT_NAME___',
78+
)
79+
end
80+
```
81+
82+
{% capture __alert_content -%}
83+
By default fastlane will connect to sentry.io. For on-prem you need to provide the _api_host_ parameter to instruct the tool to connect to your server:
84+
85+
```
86+
api_host: 'https://mysentry.invalid/'
87+
```
88+
{%- endcapture -%}
89+
{%- include components/alert.html
90+
title="On Prem"
91+
content=__alert_content
92+
%}
93+
94+
<!-- WIZARD -->
95+
### Uploading Symbols with _sentry-cli_
96+
97+
Your project’s dSYM can be upload during the build phase as a “Run Script”. For this you need to set the _DEBUG_INFORMATION_FORMAT_ to be _DWARF with dSYM File_. By default, an Xcode project will only have _DEBUG_INFORMATION_FORMAT_ set to _DWARF with dSYM File_ in _Release_ so make sure everything is set in your build settings properly.
98+
99+
You need to have an Auth Token for this to work. You can [create an Auth Token here](https://sentry.io/api/).
100+
101+
1. Download and install [sentry-cli](https://github.com/getsentry/sentry-cli#installation)
102+
2. You will need to copy the script below into a new _Run Script_ and set your _AUTH_TOKEN_, _ORG_SLUG_, and _PROJECT_SLUG_
103+
```bash
104+
if which sentry-cli >/dev/null; then
105+
export SENTRY_ORG=___ORG_NAME___
106+
export SENTRY_PROJECT=___PROJECT_NAME___
107+
export SENTRY_AUTH_TOKEN=YOUR_AUTH_TOKEN
108+
ERROR=$(sentry-cli upload-dif "$DWARF_DSYM_FOLDER_PATH" 2>&1 >/dev/null)
109+
if [ ! $? -eq 0 ]; then
110+
echo "warning: sentry-cli - $ERROR"
111+
fi
112+
else
113+
echo "warning: sentry-cli not installed, download from https://github.com/getsentry/sentry-cli/releases"
114+
fi
115+
```
116+
3. If you are using Xcode 10 or newer, you also need to add the following line to the _Input Files_ section in the _Run Script_ from step 2:
117+
```bash
118+
${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}/Contents/Resources/DWARF/${TARGET_NAME}
119+
```
120+
121+
{% capture __alert_content -%}
122+
By default sentry-cli will connect to sentry.io. For on-prem you need to export the _SENTRY_URL_ environment variable to instruct the tool to connect to your server:
123+
124+
```bash
125+
export SENTRY_URL=https://mysentry.invalid/
126+
```
127+
{%- endcapture -%}
128+
{%- include components/alert.html
129+
title="On Prem"
130+
content=__alert_content
131+
%}
132+
<!-- ENDWIZARD -->

‎src/collections/_documentation/platforms/cocoa/index.md

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
---
2+
title: Cocoa
3+
---
4+
5+
{% capture __alert_content -%}
6+
Version `5.0.0` is in beta.
7+
{%- endcapture -%}
8+
{%- include components/alert.html
9+
title="Note"
10+
content=__alert_content
11+
level="info"
12+
%}
13+
14+
This is the documentation for our Cocoa SDK (Swift and Objective-C).
15+
If you are migrating from an older version, please consider our [Migration Guide](https://github.com/getsentry/sentry-cocoa/blob/master/MIGRATION.md). Also always make sure to follow the [changelog](https://github.com/getsentry/sentry-cocoa/blob/master/CHANGELOG.md)
16+
17+
<!-- WIZARD -->
18+
## Installation {#install}
19+
20+
The SDK can be installed using [CocoaPods](http://cocoapods.org), [Carthage](https://github.com/Carthage/Carthage), or [Swift Package Manager](https://swift.org/package-manager/). This is the recommended SDK for both Swift and Objective-C projects.
21+
22+
It supports iOS (>= 8.0), tvOS (>= 9.0), macOS (>= 10.10) and partially watchOS (>= 2.0).
23+
24+
### CocoaPods
25+
26+
We recommend installing the SDK with CocoaPods..
27+
To integrate Sentry into your Xcode project, specify it in your _Podfile_:
28+
29+
```ruby
30+
platform :ios, '8.0'
31+
use_frameworks! # This is important
32+
33+
target 'YourApp' do
34+
pod 'Sentry', :git => 'https://github.com/getsentry/sentry-cocoa.git', :tag => '5.0.0-beta.0'
35+
end
36+
```
37+
<!-- {% sdk_version sentry.cocoa %} -->
38+
39+
Afterwards run `pod install`.
40+
41+
### Carthage
42+
43+
To integrate Sentry into your Xcode project using Carthage, specify it in your _Cartfile_:
44+
45+
```ruby
46+
github "getsentry/sentry-cocoa" "5.0.0-beta.0"
47+
```
48+
49+
Run `carthage update` to download the framework and drag the built _Sentry.framework_ into your Xcode project.
50+
51+
We also provide a pre-built version for every release which can be downloaded at [releases on GitHub](https://github.com/getsentry/sentry-cocoa/releases).
52+
53+
### Swift Package Manager
54+
55+
To integrate Sentry into your Xcode project using SPM, open your App in Xcode and open `File` -> `Swift Packages` -> `Add Package Dependency`. Then add the SDK by entering the git repo url `https://github.com/getsentry/sentry-cocoa.git`, and select a version (or branch) on the next page.
56+
57+
NOTE: Version tags or branches need to have the Package.swift file in it or Xcode won't be able to install the package.
58+
59+
## Configuration {#configure}
60+
61+
Make sure you initalize the SDK as soon as possible in your application lifecycle e.g. in your AppDelegate `application:didFinishLaunchingWithOptions` method:
62+
63+
{% include components/platform_content.html content_dir='init' %}
64+
65+
## Debug Symbols {#sentry-cocoa-debug-symbols}
66+
67+
Before capturing crashes, you need to provide debug information to Sentry. Debug information is provided by uploading dSYM files using one of two methods, dependent on your setup:
68+
69+
- [With Bitcode]({%- link _documentation/platforms/cocoa/dsym.md -%}#dsym-with-bitcode)
70+
- [Without Bitcode]({%- link _documentation/platforms/cocoa/dsym.md -%}#dsym-without-bitcode)
71+
72+
<!-- ENDWIZARD -->
73+
74+
## Testing if the SDK works
75+
76+
To validate that the SDK is correctly set up and connected to your Sentry project, capture a test message:
77+
78+
{% include components/platform_content.html content_dir='captureMessage' %}
79+
80+
If everything is working correctly, this message should appear within seconds in your Sentry project.
81+
82+
## Crash Handling
83+
84+
Our SDK hooks into all signal and exception handlers, except for MacOS. If you are using MacOS, please see the additional step provided in [Advanced Usage]({%- link _documentation/platforms/cocoa/usage.md -%})
85+
To try it out, the SDK provides a test crash function:
86+
87+
{% include components/platform_content.html content_dir='crash' %}
88+
89+
_If you crash with a debugger attached, nothing will happen._
90+
91+
Crashes are submitted only upon re-launch of the application. To view the crash in Sentry, close your app and re-launch it.
92+
93+
94+
## Deep Dive
95+
96+
- [Uploading Debug Symbols]({%- link _documentation/platforms/cocoa/dsym.md -%})
97+
- [With Bitcode]({%- link _documentation/platforms/cocoa/dsym.md -%}#with-bitcode)
98+
- [Without Bitcode]({%- link _documentation/platforms/cocoa/dsym.md -%}#without-bitcode)
99+
- [Advanced Usage]({%- link _documentation/platforms/cocoa/usage.md -%})

‎src/collections/_documentation/platforms/cocoa/init/objc.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
```objc
2+
@import Sentry;
3+
4+
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
5+
[SentrySDK initWithOptions:@{
6+
@"dsn": @"___PUBLIC_DSN___",
7+
@"debug": @(YES)
8+
}];
9+
return YES;
10+
}
11+
```

‎src/collections/_documentation/platforms/cocoa/init/swift.md

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
```swift
2+
import Sentry // Make sure you import Sentry
3+
4+
// ....
5+
6+
func application(_ application: UIApplication,
7+
didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
8+
_ = SentrySDK(options: [
9+
"dsn": "___PUBLIC_DSN___",
10+
"debug": true // Enabled debug when first installing is always helpful
11+
])
12+
return true
13+
}
14+
```

‎src/collections/_documentation/platforms/cocoa/integrations/objc.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
```objc
2+
NSMutableArray *integrations = [SentryOptions defaultIntegrations].mutableCopy;
3+
[integrations removeObject:@"SentryUIKitMemoryWarningIntegration"];
4+
[SentrySDK initWithOptions:@{
5+
// ...
6+
@"integrations": integrations
7+
// ...
8+
}];
9+
```

‎src/collections/_documentation/platforms/cocoa/integrations/swift.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
```swift
2+
_ = SentrySDK(options: [
3+
//...
4+
"integrations": Sentry.Options.defaultIntegrations().filter { (name) -> Bool in
5+
return name != "SentryUIKitMemoryWarningIntegration" // This will disable SentryUIKitMemoryWarningIntegration
6+
}
7+
//...
8+
])
9+
```

0 commit comments

Comments
 (0)