Migrate from `PrivateSentrySDKOnly` to `SentryObjCSDK.internal`

[philprime]

sentry-cocoa 9.19.0 introduces a new structured hybrid SDK API via SentrySDK.internal (Swift) and SentryObjCSDK.internal (ObjC). The old PrivateSentrySDKOnly class is deprecated and will be removed in the next major version.

Implementation PR: getsentry/sentry-cocoa#8097
Design doc: SENTRY-INTERNAL-API.md

Benefits

• Eliminates internal header imports. Drop PrivateSentrySDKOnly.h and Sentry-Swift.h. The new API is fully public via <SentryObjC/SentryObjC.h>.
• Proper debug image lookup API. SentryBinaryImageCache (internal class accessed directly) is replaced by [[SentryObjCSDK internal] debug] which accepts NSArray<NSNumber *> addresses directly — no string conversion needed.
• SPM / xcframework compatible. Works with binary distribution — no exposed private headers.

Import Change

Godot's iOS code is Objective-C++ (.mm) — migrate to the SentryObjC target:

// Before
#import <Sentry/PrivateSentrySDKOnly.h>
#import <Sentry/Sentry-Swift.h>  // in cocoa_includes.h

// After — single import, no internal headers
#import <SentryObjC/SentryObjC.h>

Key Changes

SDK Name

Before	After
[PrivateSentrySDKOnly setSdkName:@"sentry.cocoa.godot"]	[SentryObjCSDK internal].sdk.name = @"sentry.cocoa.godot"

Tracing

Before	After
[PrivateSentrySDKOnly setTrace:trace_id spanId:span_id]	[[SentryObjCSDK internal] setTrace:trace_id spanId:span_id]

Note: If trace_id and span_id are currently SentryId / SentrySpanId (Swift types from Sentry-Swift.h), replace with SentryObjCId / SentryObjCSpanId:

SentryObjCId *traceId = [[SentryObjCId alloc] initWithUUIDString:traceString];
SentryObjCSpanId *spanId = [[SentryObjCSpanId alloc] initWithValue:spanString];
[[SentryObjCSDK internal] setTrace:traceId spanId:spanId];

Debug Images (.debug)

Before	After
SentryBinaryImageCache + [cache imageByAddress:]	[[[SentryObjCSDK internal] debug] imagesForAddresses:@[@(address)]]

The new API accepts NSArray<NSNumber *> of UInt64 addresses directly and returns NSArray<SentryObjCDebugMeta *>, eliminating the need to import internal SentryBinaryImageCache and SentryDependencies.

Affected Files (as of latest main)

• src/sentry/cocoa/cocoa_sdk.mm — setSdkName:, setTrace:spanId:
• src/sentry/cocoa/cocoa_includes.h — Sentry-Swift.h import
• src/sentry/cocoa/cocoa_debug_images.mm — SentryBinaryImageCache direct access

Checklist

• Replace PrivateSentrySDKOnly call sites with [SentryObjCSDK internal].*
• Replace SentryBinaryImageCache direct access with [[SentryObjCSDK internal] debug]
• Remove Sentry-Swift.h import from cocoa_includes.h
• Change import to #import <SentryObjC/SentryObjC.h>
• Replace SentryId / SentrySpanId with SentryObjCId / SentryObjCSpanId
• Bump minimum sentry-cocoa dependency to 9.19.0+
• Run full test suite to verify no regressions

[linear-code]

GODOT-220

[limbonaut]

Already there since 2.0.0. The only thing left is to adopt the debug images API (instead of the current workaround), so keeping this open for now.

[limbonaut]

Done!

[NinjaLikesCheez]

@limbonaut Hi! I noticed on PrivateSentrySDKOnly call left here:

sentry-godot/src/sentry/cocoa/cocoa_sdk.mm

Line 322 in 5567044

[SentryObjCPrivateSDKOnly setTrace:trace_id spanId:span_id];

. In sentry-cocoa 9.29.0 we removed this entirely, godot uses 9.28.0 currently, but before upgrading will need to remove this last call.

This is related to an quick scan I'm doing after getsentry/sentry-cocoa#9074 was reported. Thanks!

[limbonaut]

I'll take a look @NinjaLikesCheez Thanks!