setGameQueryClipboardListener

设置游戏剪贴板查询监听器

setGameQueryClipboardListener 用于注册一个回调接口，当小游戏内部逻辑尝试读取系统剪贴板（如获取邀请码、跳转口令等）时，SDK 会通过该监听器向宿主 App 发起询问。由于 iOS 系统的隐私安全机制，SDK 将读取权限交由原生层控制。

---

方法声明

/**
 * 设置游戏查询剪贴板监听。
 * @param listener 遵循 SUDRTGameQueryClipboardListener 协议的对象。
 */
- (void)setGameQueryClipboardListener:(nullable id<SUDRTGameQueryClipboardListener>)listener;

---

参数说明

参数名	类型	必传	描述
listener	id<SUDRTGameQueryClipboardListener>	否	监听器实例。传入 nil 则取消监听。

---

运行行为

1. 触发拦截：当小游戏调用 getClipboardData 接口时，引擎不会直接访问系统 UIPasteboard，而是触发此监听器。
2. 异步响应：宿主 App 收到回调后，可以根据业务需求决定是否允许读取，或者对剪贴板内容进行预处理。
3. 隐私保护：该机制允许 App 在弹出 iOS 系统剪贴板读取提示前，执行自定义的权限确认 UI。

---

代码示例

通过该监听器，原生层可以过滤或直接返回特定的剪贴板数据给游戏：

// 1. 实现协议
@interface GameViewController () <SUDRTGameQueryClipboardListener>
@end

@implementation GameViewController

- (void)setupClipboardListener {
    // 2. 注册监听
    [self.gameHandle setGameQueryClipboardListener:self];
}

#pragma mark - SUDRTGameQueryClipboardListener

- (void)onGameQueryClipboard:(void (^)(NSString * _Nullable content))completion {
    // 3. 读取系统剪贴板（建议在主线程执行）
    dispatch_async(dispatch_get_main_queue(), ^{
        UIPasteboard *pasteboard = [UIPasteboard generalPasteboard];
        NSString *content = pasteboard.string;
        
        // 4. 将内容回调给小游戏引擎
        if (completion) {
            completion(content);
        }
        NSLog(@"[SUD] 已响应小游戏的剪贴板查询请求");
    });
}

@end

---

注意事项

• 必须回调：收到 onGameQueryClipboard: 后，务必调用 completion Block。如果不调用，小游戏内部的异步 Promise 将永远处于等待状态，可能导致业务逻辑卡死。
• iOS 隐私提示：在 iOS 14+ 系统中，直接访问 UIPasteboard.string 可能会触发系统顶部的粘贴提示。如果 App 希望避免此提示，可以先检查 hasStrings 属性。
• 数据过滤：原生层可以在回调给游戏前对 content 进行正则匹配，仅当符合邀请码格式时才返回内容，从而保护用户隐私。
• 线程安全：UIPasteboard 操作必须在主线程进行，请确保在 dispatch_get_main_queue() 中执行读取逻辑。

---