Skip to content

Commit 82ab2b8

Browse files
buenaflorbuenaflor
authored
chore: update docs (#94)
* Update docs * Update README.md
1 parent 70d2610 commit 82ab2b8

File tree

1 file changed

+34
-199
lines changed

1 file changed

+34
-199
lines changed

‎README.md

Lines changed: 34 additions & 199 deletions
Original file line numberDiff line numberDiff line change
@@ -8,216 +8,51 @@
88
<h1>Experimental Sentry SDK for Kotlin Multiplatform</h1>
99
</p>
1010

11-
This project is an experimental SDK for Kotlin Multiplatform.
12-
This SDK is a wrapper around different platforms such as JVM, Android, iOS, macOS, watchOS, tvOS that can be used on Kotlin Multiplatform.
11+
_Bad software is everywhere, and we're tired of it. Sentry is on a mission to help developers write
12+
better software faster, so we can get back to enjoying technology. If you want to join
13+
us [<kbd>**Check out our open positions**</kbd>](https://sentry.io/careers/)_
14+
15+
This SDK is a wrapper around different platforms such as JVM, Android, iOS, macOS, watchOS, tvOS
16+
that can be used on Kotlin Multiplatform.
1317

1418
[![Kotlin](https://img.shields.io/badge/Kotlin-1.8.0-blue.svg?style=flat&logo=kotlin)](https://kotlinlang.org)
1519

16-
| Packages | Maven Central
17-
|-----------------------------------------| -------
18-
| sentry-kotlin-multiplatform | [![Maven Central](https://maven-badges.herokuapp.com/maven-central/io.sentry/sentry-kotlin-multiplatform/badge.svg)](https://maven-badges.herokuapp.com/maven-central/io.sentry/sentry-kotlin-multiplatform)
20+
| Packages | Maven Central
21+
|-----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
22+
| sentry-kotlin-multiplatform | [![Maven Central](https://maven-badges.herokuapp.com/maven-central/io.sentry/sentry-kotlin-multiplatform/badge.svg)](https://maven-badges.herokuapp.com/maven-central/io.sentry/sentry-kotlin-multiplatform)
1923

2024
## Supported Platforms
2125

22-
| Target Platform | Target preset |
23-
|:-------------:|-------------|
24-
| Android | <ul><li>`android`</li></ul> |
25-
| Kotlin/JVM | <ul><li>`jvm`</li></ul>
26-
| iOS | <ul><li>`iosArm64`</li><li>`iosX64`</li><li>`iosSimulatorArm64`</li></ul>|
27-
| macOS | <ul><li>`macosArm64`</li><li>`macosX64`</ul>|
28-
| watchOS | <ul><li>`watchosArm32`</li><li>`watchosArm64`</li><li>`watchosX64`</li><li>`watchosSimulatorArm64`</li></ul>|
29-
| tvOS | <ul><li>`tvosArm64`</li><li>`tvosX64`</li><li>`tvosSimulatorArm64`</li></ul>|
30-
31-
## Configure Repository
32-
33-
The Kotlin Multiplatform SDK is available on `mavenCentral`. You can declare this repository in your build script as follows:
34-
35-
```gradle
36-
repositories {
37-
mavenCentral()
38-
}
39-
```
40-
41-
## Add dependency
42-
For a multiplatform project, you need to add the sentry-kotlin-multiplatform artifact to the `commonMain` source set:
43-
44-
```Kotlin
45-
val commonMain by getting {
46-
dependencies {
47-
api("io.sentry:sentry-kotlin-multiplatform:<version>")
48-
}
49-
}
50-
```
51-
52-
### Cocoa
53-
54-
If you are targeting Apple platforms (iOS, macOS, watchOS, tvOS), then you can use CocoaPods to include [Sentry Cocoa](https://github.com/getsentry/sentry-cocoa) into this SDK.
55-
One way to achieve this is to include the Sentry Cocoa SDK via the Kotlin CocoaPods extension. Be aware that your Sentry Cocoa version has to match the version used in the KMP SDK.
56-
57-
```gradle
58-
cocoapods {
59-
// ...
60-
61-
// Make sure Sentry Cocoa in your project matches this version
62-
pod("Sentry", "~> 8.4.0")
63-
64-
framework {
65-
baseName = "shared"
66-
67-
// Export the SDK in order to be able to access it directly in the iOS project
68-
export("io.sentry:sentry-kotlin-multiplatform:<version>")
69-
}
70-
}
71-
```
72-
73-
### Swift Package Manager
74-
75-
Alternatively you can use the Swift Package Manager to include the Sentry Cocoa SDK into this SDK.
76-
Open your iOS app in Xcode and open File > Add Packages. Then add the SDK by entering the git repo url in the top right search field:
77-
`https://github.com/getsentry/sentry-cocoa.git`
78-
79-
After adding the package, you need to add the following to your shared `build.gradle.kts`:
80-
81-
```gradle
82-
listOf(
83-
iosX64(),
84-
iosArm64(),
85-
iosSimulatorArm64(),
86-
// ... other Apple targets
87-
).forEach {
88-
it.binaries.framework {
89-
baseName = "shared"
90-
isStatic = true
91-
92-
// Export the SDK in order to be able to access it directly in the iOS project
93-
export("io.sentry:sentry-kotlin-multiplatform:<version>")
94-
}
95-
}
96-
```
97-
98-
## Initialization
99-
100-
There are two main strategies for initializing the SDK:
101-
- Shared initializer
102-
- Platform-specific initializers
103-
104-
Shared initializer will initialize the SDK in your shared codebase but you will use the same configuration options for all platforms.
105-
106-
Platform-specific initializers initialize the SDK directly in the target platform. The benefit is being able to customize the configuration options specific to the platforms.
107-
108-
It is also possible to mix those two strategies based on your needs and project setup.
109-
110-
## Prerequisites (Android-only)
111-
112-
Both of the strategies require disabling auto-init on Android to not clash with the `ContentProvider`, which auto-initializes the Sentry Android SDK. To do so, add the following to the `AndroidManifest.xml` file under your `androidMain` source set:
113-
114-
```xml
115-
<application>
116-
<meta-data android:name="io.sentry.auto-init" android:value="false" />
117-
</application>
118-
```
119-
120-
## Shared Initializer
121-
122-
Create a Kotlin file in your commonMain e.g. `AppSetup.kt` or however you want to call it and create a function that will initialize the SDK.
123-
124-
```Kotlin
125-
import io.sentry.kotlin.multiplatform.Context
126-
import io.sentry.kotlin.multiplatform.Sentry
127-
import io.sentry.kotlin.multiplatform.OptionsConfiguration
128-
129-
// The context is needed for Android initializations
130-
fun initializeSentry(context: Context) {
131-
Sentry.init(context, optionsConfiguration())
132-
}
133-
134-
fun initializeSentry() {
135-
Sentry.init(optionsConfiguration())
136-
}
137-
138-
private fun optionsConfiguration(): OptionsConfiguration = {
139-
it.dsn = "__DSN__"
140-
}
141-
142-
```
143-
144-
Now call this function in an early lifecycle stage in your platforms.
145-
146-
### Android
147-
```Kotlin
148-
import your.kmp.app.initializeSentry
149-
150-
class YourApplication : Application() {
151-
override fun onCreate() {
152-
super.onCreate()
153-
// Make sure to add the context!
154-
initializeSentry(this)
155-
}
156-
}
157-
```
158-
159-
### Cocoa
160-
161-
```Swift
162-
import shared
163-
164-
class AppDelegate: NSObject, UIApplicationDelegate {
165-
func application(
166-
_ application: UIApplication,
167-
didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil
168-
) -> Bool {
169-
AppSetupKt.initializeSentry()
170-
return true
171-
}
172-
}
173-
```
174-
175-
## Platform-Specific Initializers
176-
### Android
177-
178-
```Kotlin
179-
import io.sentry.kotlin.multiplatform.Sentry
180-
181-
class YourApplication : Application() {
182-
override fun onCreate() {
183-
super.onCreate()
184-
// Make sure to add the context!
185-
Sentry.init(this) {
186-
it.dsn = "___DSN___"
187-
}
188-
}
189-
}
190-
```
191-
192-
### Cocoa
193-
```Swift
194-
import shared
26+
| Target Platform | Target preset |
27+
|:---------------:|--------------------------------------------------------------------------------------------------------------|
28+
| Android | <ul><li>`android`</li></ul> |
29+
| Kotlin/JVM | <ul><li>`jvm`</li></ul>
30+
| iOS | <ul><li>`iosArm64`</li><li>`iosX64`</li><li>`iosSimulatorArm64`</li></ul> |
31+
| macOS | <ul><li>`macosArm64`</li><li>`macosX64`</ul> |
32+
| watchOS | <ul><li>`watchosArm32`</li><li>`watchosArm64`</li><li>`watchosX64`</li><li>`watchosSimulatorArm64`</li></ul> |
33+
| tvOS | <ul><li>`tvosArm64`</li><li>`tvosX64`</li><li>`tvosSimulatorArm64`</li></ul> |
19534

196-
class AppDelegate: NSObject, UIApplicationDelegate {
197-
func application(
198-
_ application: UIApplication,
199-
didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil
200-
) -> Bool {
201-
Sentry.shared.doInit() { options in
202-
options.dsn = "__DSN__"
203-
}
204-
return true
205-
}
206-
}
207-
```
35+
## Usage
20836

209-
## Debug Symbols for Apple targets
37+
For detailed usage, check out the [Kotlin Multiplatform Documentation](https://docs.sentry.io/platforms/kotlin-multiplatform/).
21038

211-
A dSYM upload is required for Sentry to symbolicate your crash logs for viewing. The symbolication 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 tool or through a Fastlane action. Please visit our [sentry.io guide](https://docs.sentry.io/platforms/apple/dsym/) to get started on uploading debug symbols.
39+
## Samples
21240

213-
## Troubleshooting
41+
For detailed information on how to build and run the samples, check out our `README.md` in the
42+
[sentry-samples](https://github.com/getsentry/sentry-kotlin-multiplatform/tree/main/sentry-samples)
43+
folder.
21444

215-
`WARNING: CocoaPods requires your terminal to be using UTF-8 encoding.
216-
Consider adding the following to ~/.profile:
217-
export LANG=en_US.UTF-8`
45+
## Contribution
21846

219-
This is a known problem and can easily be fixed as described in this [Stack Overflow post](https://stackoverflow.com/a/69395720)
47+
Please see
48+
the [contribution guide](https://github.com/getsentry/sentry-kotlin-multiplatform/blob/main/CONTRIBUTING.md)
49+
before contributing
22050

221-
## Contribution
51+
# Resources
22252

223-
Please see the [contribution guide](https://github.com/getsentry/sentry-kotlin-multiplatform/blob/main/CONTRIBUTING.md) before contributing
53+
* [![Kotlin Multiplatform Documentation](https://img.shields.io/badge/documentation-sentry.io-green.svg?label=documentation)](https://docs.sentry.io/platforms/kotlin-multiplatform/)
54+
* [![Discussions](https://img.shields.io/github/discussions/getsentry/sentry-kotlin-multiplatform.svg)](https://github.com/getsentry/sentry-kotlin-multiplatform/discussions)
55+
* [![Discord Chat](https://img.shields.io/discord/621778831602221064?logo=discord&logoColor=ffffff&color=7389D8)](https://discord.gg/PXa5Apfe7K)
56+
* [![Stack Overflow](https://img.shields.io/badge/stack%20overflow-sentry-green.svg)](http://stackoverflow.com/questions/tagged/sentry)
57+
* [![Code of Conduct](https://img.shields.io/badge/code%20of%20conduct-sentry-green.svg)](https://github.com/getsentry/.github/blob/master/CODE_OF_CONDUCT.md)
58+
* [![Twitter Follow](https://img.shields.io/twitter/follow/getsentry?label=getsentry&style=social)](https://twitter.com/intent/follow?screen_name=getsentry)

0 commit comments

Comments
 (0)