onGetLegacyUserIdentity:dataJson
Retrieve Legacy User Identity
This method is used by a new game package to retrieve the original App user's identity. Its main purpose: when a new game version starts, after the original App user logs in successfully, the game needs to retrieve the original App user's identity for subsequent game data synchronization.
Method Declaration
objectivec
/**
* Triggered when the SDK requests the Legacy User Identity.
* Typically used to be compatible with legacy systems or to migrate existing user data.
*
* @param stateHandle The state handle used to return the processing result to the SDK.
* @param dataJson A JSON string containing request parameters (such as the current user ID) or context information.
*/
- (void)onGetLegacyUserIdentity:(id<SUDOPStateHandle>)stateHandle dataJson:(NSString*)dataJson;Runtime Behavior
- Retroactive trigger: During initialization or when syncing cloud saves, the game engine initiates this call if it detects that a legacy account needs to be mapped.
- Data pass-through: The
dataJsonfield contains context provided by the game side (for example, a legacy account index defined internally by the game or a specific migration marker). - Asynchronous decision: After receiving the request, the App can perform an asynchronous query (such as accessing the App Server to exchange for the Legacy ID) and close the loop via
stateHandleupon completion. - Result return: The App must return a JSON string containing
legacyUserId. If the user has no legacy identity, it usually returns the currentuserIdor an empty JSON.
Code Example (Objective-C)
Implement the query and return of the legacy ID:
objectivec
- (void)onGetLegacyUserIdentity:(id<SUDOPStateHandle>)stateHandle dataJson:(NSString*)dataJson {
// 1. Parse the request parameters
NSData *requestData = [dataJson dataUsingEncoding:NSUTF8StringEncoding];
NSDictionary *requestDict = [NSJSONSerialization JSONObjectWithData:requestData options:0 error:nil];
NSString *currentUserId = requestDict[@"userId"];
// 2. Simulate retrieving the legacy ID corresponding to this user from the App business layer
// It may be an MD5-hashed device identifier or an auto-increment ID from the legacy system
NSString *legacyId = [MyUserCenter getLegacyIdForUser:currentUserId];
// 3. Construct the return result that conforms to the protocol requirements
NSDictionary *result = @{
@"legacyUserId": legacyId ?: @""
};
// 4. Convert to JSON and return
NSData *resultData = [NSJSONSerialization dataWithJSONObject:result options:0 error:nil];
NSString *resultJson = [[NSString alloc] initWithData:resultData encoding:NSUTF8StringEncoding];
[stateHandle success:resultJson];
}Notes
- Non-blocking requirement: Although iOS provides powerful multithreading capabilities, avoid performing synchronous network requests or time-consuming database operations in this callback; asynchronous tasks are recommended.
- Return value convention: If your business does not need to distinguish between new and legacy IDs, it is recommended to return the current
userIddirectly, to ensure the game logic can continue to execute. - stateHandle closed loop: You must ensure that
[stateHandle success:]or[stateHandle fail:]is called. If the method finishes without giving an explicit response, the SDK may internally treat it as a request timeout, causing the game flow to freeze.
