Skip to content

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 dataJson field 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 stateHandle upon completion.
  • Result return: The App must return a JSON string containing legacyUserId. If the user has no legacy identity, it usually returns the current userId or 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 userId directly, 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.