iOS Quick Integration
Follow this guide to integrate the SUDGI SDK and advertising capabilities, complete SDK initialization and user authentication, then launch games.
1. Import the SDK and Configure the Project
1. Import the SDK
CocoaPods
Add the following to the host app target in Podfile:
sdk_version = '3.0.0'
pod 'SUDGI', sdk_version
# Choose at least one ad source
pod 'SUDM/admob', sdk_version
pod 'SUDM/carty', sdk_version
pod 'SUDM/topon', sdk_version
pod 'SUDM/max', sdk_version
pod 'SUDM/taku', sdk_versionUse sdk_version to specify the matching SDK release version for SUDGI and SUDM in one place. When upgrading, update this variable and the complete SDK set together. Keep only the ad sources you use, then run pod install. CocoaPods automatically installs their base components and ad-platform SDK dependencies.
Manual Import
Drag SUDGI.xcframework into the project and set it to Embed & Sign under General. Add the advertising libraries and resources from the matching delivery package:
- Shared components:
SUDCoreKit.xcframeworkandSUDReport.xcframework; add each only once if already present. - Advertising core:
SUDM.xcframework. - Selected adapters: choose from
SUDMAdapterAdmob.xcframework,SUDMAdapterCarty.xcframework,SUDMAdapterTopOn.xcframework,SUDMAdapterMax.xcframework, andSUDMAdapterTaku.xcframework. - The selected ad-platform SDKs, their dependencies, and accompanying resource bundles.
Add the libraries to the host app target, and configure linking and embedding according to each library’s delivery instructions. Add separately supplied resource bundles and privacy manifests to Copy Bundle Resources without duplicating resources already packaged in frameworks.
2. Environment Settings
- Other Linker Flags: Add
-ObjC. - Enable Bitcode: Set to NO.
- Import the header:
#import <SUDGI/SUDGI-umbrella.h>.
3. Third-party Version Requirements
Use the versions and dependency constraints below as the integration baseline. Do not downgrade the bundled dependencies. Before upgrading, consult the official version information and confirm compatibility with the SUD components you use.
| Third-party module | Integration baseline / version constraint | Version information |
|---|---|---|
AdMob: Google-Mobile-Ads-SDK | Paired version 13.7.0; CocoaPods constraint ~> 13.7.0 | Google release notes |
Carty: CartySDK | Fixed at 1.10.0 | Carty changelog |
TopOn: TPNiOS | Fixed at 6.5.73 | TopOn iOS integration guide |
MAX: AppLovinSDK | Paired version 13.6.3; CocoaPods constraint ~> 13.6.3 | MAX iOS integration guide |
Taku: AnyThinkiOS | Fixed at 6.5.83 | Taku iOS integration guide |
2. Advertising Integration
With the dependencies installed, configure the host app for the selected ad sources and complete the applicable consent flow before SDK initialization.
Host Configuration
AdMob App ID
Required when using AdMob. Add the following to the host app target's Info.plist.
<key>GADApplicationIdentifier</key>
<string>ca-app-pub-XXXXXXXXXXXXXXXX~YYYYYYYYYY</string>Replace the value with the iOS app ID from the AdMob console (containing ~), not an ad unit ID (containing /).
Google's test app ID is ca-app-pub-3940256099942544~1458002511. SDK resources do not automatically add this setting to the host Info.plist; configure it in the host app. See AdMob iOS setup.
SKAdNetwork
SKAdNetwork supports install attribution without IDFA; identifiers end in .skadnetwork. See AdMob iOS privacy strategies.
Edit the host app target's Info.plist. Merge and deduplicate IDs required by the ad sources you integrate. The single ID below only illustrates the format; complete the list for your integration.
<key>SKAdNetworkItems</key>
<array>
<dict>
<key>SKAdNetworkIdentifier</key>
<string>cstr6suwn9.skadnetwork</string>
</dict>
<!-- Only one Google ID is shown; complete the list using the sources below. -->
</array>| Ad source | ID list to use |
|---|---|
| AdMob | Google and third-party buyer SKAdNetwork IDs |
User Consent and Authorization
User Consent
The SDK accepts host-confirmed states; it does not determine legal applicability or display consent dialogs. SUDOPPrivacyConfig does not replace CMP, UMP, or ATT flows.
Required when advertising consent must be collected. Complete this integration before SDK initialization.
Reuse the host's CMP or privacy flow. When using Google UMP iOS, update consent information, show required forms, provide a privacy-options entry point when required, and check UMPConsentInformation.sharedInstance.canRequestAds before requesting ads.
Pass the host's confirmed privacy states into initialization in the next section. Do not map canRequestAds directly to all four states being granted.
ATT
Required when the app or an ad SDK tracks across apps or websites, or accesses IDFA. Obtain ATT authorization first on iOS 14.5 and later.
First integration point: add a purpose string to the host's Info.plist and tailor it to your product's actual use.
<key>NSUserTrackingUsageDescription</key>
<string>Used to show you more relevant advertising.</string>Second integration point: the host's authorization flow. If UMP already handles ATT, reuse that flow. Otherwise, link AppTrackingTransparency and request authorization manually; do not request it twice. The following only demonstrates the ATT call. Continue with SDK initialization after handling the required authorization flows.
#import <AppTrackingTransparency/AppTrackingTransparency.h>
// Call on the main thread while the app is active, with no other system permission dialog.
if (@available(iOS 14.0, *)) {
[ATTrackingManager requestTrackingAuthorizationWithCompletionHandler:^(ATTrackingManagerAuthorizationStatus status) {
dispatch_async(dispatch_get_main_queue(), ^{
// After ATT and the CMP flow finish, continue with SDK initialization in the next section.
// Authorized permits tracking; Denied / Restricted do not.
// NotDetermined is not authorization; handle it at an appropriate time.
// Do not treat ATT status as GDPR / LGPD consent.
});
}];
} else {
// No ATT API: follow the host's privacy flow before SDK initialization in the next section.
}Ad integration does not require the host to read or pass IDFA manually. If your own business logic needs it, use AdSupport only after authorization and do not treat an all-zero IDFA as valid. Also review the ad SDKs' actual collection behavior. See Apple's tracking authorization requirements.
3. SDK Initialization
Complete the advertising dependencies, host configuration, and applicable consent and ATT flows above, then initialize the SDK once during app startup with the host-confirmed privacy states.
See SUDOPPrivacyConfig for fields and enum definitions. Replace the sample app ID, app key, and privacy states; the values below illustrate syntax, not default consent.
SUDOPPrivacyConfig *privacyConfig = [[SUDOPPrivacyConfig alloc] init];
// Assign only the states confirmed by the host; unassigned fields keep the
// default Unset value and are not applied to the ad SDK.
privacyConfig.gdprConsentStatus = kSUDOPGdprConsentStatusNotApplicable;
privacyConfig.doNotSellStatus = kSUDOPDoNotSellStatusNotApplicable;
privacyConfig.lgpdConsentStatus = kSUDOPLgpdConsentStatusNotApplicable;
privacyConfig.ageRestrictedTreatment = kSUDOPAgeRestrictedTreatmentUnspecified;
SUDOPSDKConfiguration *config = [[SUDOPSDKConfiguration alloc] init];
config.appId = @"YOUR_APP_ID";
config.appKey = @"YOUR_APP_KEY";
config.privacyConfig = privacyConfig;
[SUDOP initializeWithConfiguration:config completion:^(NSError * _Nullable error) {
if (error) {
NSLog(@"OP initialization failed: %@", error.localizedDescription);
return;
}
// Continue with OP authentication and game startup.
}];See initializeWithConfiguration for the complete initialization API.
4. User Authentication (auth)
Before launching the game, you must pass the userSignature generated by your business backend to the SDK.
// 1. userSignature is generated and issued by your business server
NSString *userSignature = @"Signature string issued by the business backend";
// 2. Establish a valid user session
[SUDOP authWithUserSignature:userSignature completion:^(NSError * _Nullable error) {
if (!error) {
NSLog(@"Authentication successful");
}
}];After authentication succeeds, the SDK uses user ping to detect invalidation. Register an account-level setAuthInvalidatedListener: listener before the first auth call, and let the host fetch fresh signatures and serialize re-authentication. The SDK does not fetch signatures or retry automatically. Wait for authentication before initially loading a game, and preserve running games after recovery. End the old recovery flow and uninitialize on logout or environment changes; register the listener again when reconnecting.
5. Fast Game Launch
Pass in the gameID directly, and the SDK will automatically handle resource download, verification, and rendering.
[SUDOP startGame:@"123" didGameViewCreated:^(UIView * _Nonnull gameView) {
// 2. Mount the view to the UI
gameView.frame = self.gameContentView.bounds;
[self.gameContentView addSubview:gameView];
} didGameHandleCreated:^(id<SUDRTGameHandle> _Nonnull gameHandle, SUDOPGameInfo * _Nonnull gameInfo) {
// Save the handle for later destruction
self.gameHandle = gameHandle;
// 1. Register the delegate to receive game events
[SUDOP registerWrappedClientWithGameHandle:gameHandle clientDelegate:self];
} progress:^(NSInteger progress) {
} completion:^(id<SUDOPGameHandleProvider> _Nullable gameHandleProvider, NSError * _Nullable error) {
if (!error) NSLog(@"Game is running successfully");
}];Once the game is running, mini-games load and display ads through the sud ad APIs; see game developer examples. SDK initialization success does not mean an ad has loaded; game code must wait for the ad object’s onLoad.
6. Destruction and Resource Release
When the user exits the game page, destroy the instance directly through the handle.
if (self.gameHandle) {
[self.gameHandle destroy];
self.gameHandle = nil;
NSLog(@"Game instance destroyed, memory released");
}7. Release Checks
- When using AdMob, replace any test app ID with your own app ID.
- Verify settings in the final
Info.plistagainst the integrated ad sources; review SKAdNetwork IDs after SDK or ad-source upgrades. - Check SDK
PrivacyInfo.xcprivacyresources in the archive and complete App Store privacy information based on actual app and third-party SDK behavior. - SUDM's privacy manifest currently declares device identifier data for tracking; the manifest is not ATT or CMP consent.
