Migration Guide

Learn more about migrating to the current version.

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.

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:

  • Removed USentryId class and replaced its usages with FString
  • Removed USentrySubsystem::ConfigureScope function
  • Removed USentryLibrary::StringToBytesArray function
  • Removed USentryLibrary::ByteArrayToString function
  • Removed USentryLibrary::SaveStringToFile function
  • Removed USentryScope::SetEnvironment function
  • Removed USentryScope::GetEnvironment function
  • Removed USentryScope::SetDist function
  • Removed USentryScope::GetDist function

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:

  • Replace USentryUserFeedback class references with USentryFeedback
  • Replace USentrySubsystem::CaptureUserFeedback function usages with USentrySubsystem::CaptureFeedback
  • Replace USentryLibrary::CreateSentryUserFeedback function usages with USentryLibrary::CreateSentryFeedback
Copied
USentrySubsystem* SentrySubsystem = GEngine->GetEngineSubsystem<USentrySubsystem>();

FString Message = TEXT("Feedback message");
FString Name = TEXT("John Doe");
FString Email = TEXT("test@email.com");
FString EventId = TEXT("c3829f10764848442d813c4124cf44a0");

// Submitting user feedback before v1.0.0

USentryUserFeedback* Feedback = NewObject<USentryUserFeedback>();

Feedback->Initialize(EventId);

Feedback->SetName(Name);        // optional
Feedback->SetEmail(Email);      // optional
Feedback->SetComment(Message);  // optional

SentrySubsystem->CaptureUserFeedback(Feedback);

// Submitting user feedback in v1.0.0

USentryFeedback* Feedback = NewObject<USentryFeedback>();

Feedback->Initialize(Message);

Feedback->SetName(Name);                // optional
Feedback->SetContactEmail(Email);       // optional
Feedback->SetAssociatedEvent(EventId);  // optional

SentrySubsystem->CaptureFeedback(Feedback);

The USentrySubsystem::StartTransactionWithContextAndOptions function now takes an FSentryTransactionOptions struct instead of a TMap<FString, FString>, improving clarity and allowing better extensibility in the future.

Also, the USentrySamplingContext class now utilizes FSentryVariant instead of strings for custom sampling context values.

Copied
USentrySubsystem* SentrySubsystem = GEngine->GetEngineSubsystem<USentrySubsystem>();

// Starting transaction with context and options before v1.0.0

USentryTransactionContext* TransactionContext = ...

TMap<FString, FString> Options;
Options.Add("key1", "value1");
Options.Add("key2", "value2");

SentrySubsystem->StartTransactionWithContextAndOptions(TransactionContext, Options);

// Starting transaction with context and options in v1.0.0

USentryTransactionContext* TransactionContext = ...

FSentryTransactionOptions Options;
Options.CustomSamplingContext.Add("key1", FSentryVariant("value1"));
Options.CustomSamplingContext.Add("key2", FSentryVariant("value2"));

SentrySubsystem->StartTransactionWithContextAndOptions(TransactionContext, Options);

On Windows and Linux, ToString function of SentryId class now returns the sanitized string that doesn't contain dashes.

With the removal of USentrySubsystem::ConfigureScope global scope values (tags, context, attachments, etc.) should now be configured directly via the subsystem interface.

Copied
USentrySubsystem* SentrySubsystem = GEngine->GetEngineSubsystem<USentrySubsystem>();

// Configuring global scope before v1.0.0

SentrySubsystem->ConfigureScope(FConfigureScopeNativeDelegate::CreateLambda([](USentryScope* Scope)
{
    Scope->SetTag(...);
    Scope->SetContext(...);
    Scope->AddAttachment(...);
}));

// Configuring global scope in v1.0.0

SentrySubsystem->SetTag(...);
SentrySubsystem->SetContext(...);
SentrySubsystem->AddAttachment(...);

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.

  • The Environment and Dist properties must now be set in the plugin settings and can no longer be modified programmatically via scope configuration.

  • 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.

  • 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.

  • 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).

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.

  • Renamed OnError delagate property of FSentryOutputDeviceError class to OnAssert

To enable capturing editor crashes USentrySubsystem base class has been changed to UEngineSubsystem.

  • If you're using the plugin's Blueprint API, you will need to recreate all Get Sentry Subsystem nodes.
  • If you're using the plugin's C++ API, update your implementation to access USentrySubsystem via the GEngine pointer.
Previous
Set Up User Feedback
Was this helpful?
Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").