Skip to content

Commit 7f500ba

Browse files
tustanivskybruno-garcia
tustanivsky
and
bruno-garcia
authored
Unreal Engine: Add migration guide (#14186)
This PR adds Unreal Engine SDK migration guide for the upcoming `1.0.0` plugin release. Related to: - getsentry/sentry-unreal#928 - getsentry/sentry-unreal#971 - getsentry/sentry-unreal#1051 - getsentry/sentry-unreal#1018 - getsentry/sentry-unreal#886 - getsentry/sentry-unreal#745 - getsentry/sentry-unreal#436 - getsentry/sentry-unreal#589 - getsentry/sentry-unreal#1057 - getsentry/sentry-unreal#669 --------- Co-authored-by: Bruno Garcia <[email protected]>
1 parent ab2976c commit 7f500ba

File tree

2 files changed

+168
-0
lines changed

2 files changed

+168
-0
lines changed

‎docs/platforms/unreal/configuration/options.mdx

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,12 @@ By default the SDK will try to read this value from the `SENTRY_ENVIRONMENT` env
4242

4343
</ConfigKey>
4444

45+
<ConfigKey name="dist">
46+
47+
Sets the distribution of the application. Distributions are used to disambiguate build or deployment variants of the same release of an application. For example, the dist can be the build number of an Xcode build or the version code of an Android build. The dist has a max length of 64 characters.
48+
49+
</ConfigKey>
50+
4551
<ConfigKey name="sample-rate">
4652

4753
Configures the sample rate for error events, in the range of `0.0` to `1.0`. The default is `1.0`, which means that 100% of error events will be sent. If set to `0.1`, only 10% of error events will be sent. Events are picked randomly.

‎docs/platforms/unreal/migration/index.mdx

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
---
2+
title: Migration Guide
3+
description: "Learn more about migrating to the current version."
4+
sidebar_order: 8000
5+
---
6+
7+
<Alert>
8+
We recommend using this guide starting from the version closes to your current version which might require scrolling further down before jumping to the latest guide.
9+
</Alert>
10+
11+
## Migrating to 1.0.0
12+
13+
### Breaking changes
14+
15+
#### Sentry Classes Instantiation
16+
17+
Sentry class objects created via `NewObject<T>` in C++ or `ConstructObjectFromClass` in Blueprints now require an explicit call to their `Initialize` method (if available) before use. In Blueprints, it's recommended to use the provided Sentry library functions to create these entities as they automatically call `Initialize` and return a fully initialized, ready-to-use object.
18+
19+
#### Cleanup Public Classes
20+
21+
We cleaned up our public API by removing a few functions and classes to streamline the SDK and remove ambiguities. The following changes were made:
22+
23+
- Removed `USentryId` class and replaced its usages with `FString`
24+
- Removed `USentrySubsystem::ConfigureScope` function
25+
- Removed `USentryLibrary::StringToBytesArray` function
26+
- Removed `USentryLibrary::ByteArrayToString` function
27+
- Removed `USentryLibrary::SaveStringToFile` function
28+
- Removed `USentryScope::SetEnvironment` function
29+
- Removed `USentryScope::GetEnvironment` function
30+
- Removed `USentryScope::SetDist` function
31+
- Removed `USentryScope::GetDist` function
32+
33+
#### User feedback
34+
35+
We have reworked the user feedback feature so now it no longer needs to be associated with a specific event and the only required input is the text message. If you were using this functionality in your project consider updating it accordingly:
36+
37+
- Replace `USentryUserFeedback` class references with `USentryFeedback`
38+
- Replace `USentrySubsystem::CaptureUserFeedback` function usages with `USentrySubsystem::CaptureFeedback`
39+
- Replace `USentryLibrary::CreateSentryUserFeedback` function usages with `USentryLibrary::CreateSentryFeedback`
40+
41+
```cpp
42+
USentrySubsystem* SentrySubsystem = GEngine->GetEngineSubsystem<USentrySubsystem>();
43+
44+
FString Message = TEXT("Feedback message");
45+
FString Name = TEXT("John Doe");
46+
FString Email = TEXT("[email protected]");
47+
FString EventId = TEXT("c3829f10764848442d813c4124cf44a0");
48+
49+
// Submitting user feedback before v1.0.0
50+
51+
USentryUserFeedback* Feedback = NewObject<USentryUserFeedback>();
52+
53+
Feedback->Initialize(EventId);
54+
55+
Feedback->SetName(Name); // optional
56+
Feedback->SetEmail(Email); // optional
57+
Feedback->SetComment(Message); // optional
58+
59+
SentrySubsystem->CaptureUserFeedback(Feedback);
60+
61+
// Submitting user feedback in v1.0.0
62+
63+
USentryFeedback* Feedback = NewObject<USentryFeedback>();
64+
65+
Feedback->Initialize(Message);
66+
67+
Feedback->SetName(Name); // optional
68+
Feedback->SetContactEmail(Email); // optional
69+
Feedback->SetAssociatedEvent(EventId); // optional
70+
71+
SentrySubsystem->CaptureFeedback(Feedback);
72+
```
73+
74+
#### Tracing
75+
76+
The `USentrySubsystem::StartTransactionWithContextAndOptions` function now takes an `FSentryTransactionOptions` struct instead of a `TMap<FString, FString>`, improving clarity and allowing better extensibility in the future.
77+
78+
Also, the `USentrySamplingContext` class now utilizes `FSentryVariant` instead of strings for custom sampling context values.
79+
80+
```cpp
81+
USentrySubsystem* SentrySubsystem = GEngine->GetEngineSubsystem<USentrySubsystem>();
82+
83+
// Starting transaction with context and options before v1.0.0
84+
85+
USentryTransactionContext* TransactionContext = ...
86+
87+
TMap<FString, FString> Options;
88+
Options.Add("key1", "value1");
89+
Options.Add("key2", "value2");
90+
91+
SentrySubsystem->StartTransactionWithContextAndOptions(TransactionContext, Options);
92+
93+
// Starting transaction with context and options in v1.0.0
94+
95+
USentryTransactionContext* TransactionContext = ...
96+
97+
FSentryTransactionOptions Options;
98+
Options.CustomSamplingContext.Add("key1", FSentryVariant("value1"));
99+
Options.CustomSamplingContext.Add("key2", FSentryVariant("value2"));
100+
101+
SentrySubsystem->StartTransactionWithContextAndOptions(TransactionContext, Options);
102+
```
103+
104+
#### Event ID format (Windows/Linux)
105+
106+
On Windows and Linux, `ToString` function of `SentryId` class now returns the sanitized string that doesn't contain dashes.
107+
108+
#### Global scope configuration
109+
110+
With the removal of `USentrySubsystem::ConfigureScope` global scope values (tags, context, attachments, etc.) should now be configured directly via the subsystem interface.
111+
112+
```cpp
113+
USentrySubsystem* SentrySubsystem = GEngine->GetEngineSubsystem<USentrySubsystem>();
114+
115+
// Configuring global scope before v1.0.0
116+
117+
SentrySubsystem->ConfigureScope(FConfigureScopeNativeDelegate::CreateLambda([](USentryScope* Scope)
118+
{
119+
Scope->SetTag(...);
120+
Scope->SetContext(...);
121+
Scope->AddAttachment(...);
122+
}));
123+
124+
// Configuring global scope in v1.0.0
125+
126+
SentrySubsystem->SetTag(...);
127+
SentrySubsystem->SetContext(...);
128+
SentrySubsystem->AddAttachment(...);
129+
```
130+
131+
### Issue Grouping
132+
133+
The Unreal SDK no longer modifies call stacks for assertion events by trimming the topmost frames related to the engine's internal assertion handling logic. This was previously done to work around the case where all assertions were grouped into a single Sentry issue. With this change, issue grouping is now fully handled by the Sentry server.
134+
135+
### SDK Configuration Changes
136+
137+
- The <PlatformIdentifier name="environment" /> and <PlatformIdentifier name="dist" /> properties must now be set in the plugin settings and can no longer be modified programmatically via scope configuration.
138+
139+
- Sentry can no longer be disabled for specific platforms using the `Enable for Build Platform Types` option in the plugin settings (`General -> Misc`) or the EnableTargetPlatforms property in the project configuration file.
140+
141+
- If upgrading from a version prior to 0.9.0 legacy settings `DsnUrl`, `EnableVerboseLogging` and `EnableStackTrace` will no longer be read from the project configuration file automatically. Instead, you must re-set them in plugin settings to adopt the new format.
142+
143+
- On mobile platforms, the default traces sampler will no longer be created automatically. You must now explicitly set the `Traces Sampler` property in the plugin settings to enable performance monitoring (`General -> Performance Monitoring`).
144+
145+
### Crash Reporter Changes
146+
147+
The `Epic Account Id` and `Login Id` are no longer included in the `Crash Info` context for crashes captured on Windows and Linux using the default Crash Reporter. These fields are intended for internal use by Epic Games and provide no meaningful value externally.
148+
149+
## Migrating to 0.19.0
150+
151+
### Breaking changes
152+
153+
- Renamed `OnError` delagate property of `FSentryOutputDeviceError` class to `OnAssert`
154+
155+
## Migrating to 0.15.0
156+
157+
### Breaking changes
158+
159+
To enable capturing editor crashes `USentrySubsystem` base class has been changed to `UEngineSubsystem`.
160+
161+
- If you're using the plugin's Blueprint API, you will need to recreate all `Get Sentry Subsystem` nodes.
162+
- If you're using the plugin's C++ API, update your implementation to access `USentrySubsystem` via the `GEngine` pointer.

0 commit comments

Comments
 (0)