@cloudcare/cocos-session-replay 0.1.0-alpha.6

package/native/android/src/main/java/com/ft/sdk/cocos/FTCocosReplayBridge.java

@@ -0,0 +1,168 @@
+package com.ft.sdk.cocos;
+
+import android.app.Activity;
+import com.ft.sdk.FTSdk;
+import com.ft.sdk.SessionReplayManager;
+import com.ft.sdk.sessionreplay.FTSessionReplayConfig;
+import com.ft.sdk.sessionreplay.SessionReplayInternalCallback;
+import com.ft.sdk.sessionreplay.TouchPrivacy;
+import org.json.JSONObject;
+import java.io.ByteArrayOutputStream;
+import java.io.File;
+import java.io.FileInputStream;
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+
+/** Optional native Session Replay entry point. */
+public final class FTCocosReplayBridge {
+    private FTCocosReplayBridge() {}
+    public static String invoke(String method, String payload) {
+        return FTBridgeTransport.invoke("session-replay", method, payload);
+    }
+
+    static String invokeLocal(String method, String payload) {
+        try {
+            Object value = dispatch(method, payload == null || payload.isEmpty()
+                    ? new JSONObject() : new JSONObject(payload));
+            JSONObject response = new JSONObject();
+            response.put("ok", true);
+            if (value != null) response.put("value", JSONObject.wrap(value));
+            return response.toString();
+        } catch (Throwable error) {
+            JSONObject response = new JSONObject();
+            try {
+                response.put("ok", false);
+                response.put("error", error.getClass().getSimpleName() + ": " + error.getMessage());
+            } catch (Throwable ignored) {
+                return "{\"ok\":false,\"error\":\"Native bridge failure\"}";
+            }
+            return response.toString();
+        }
+    }
+
+    private static Object dispatch(String method, JSONObject payload) throws Exception {
+        switch (method) {
+            case "replay.capabilities":
+                FTSessionReplayConfig.class.getDeclaredMethod("setExternalRecorderMode", boolean.class);
+                if (payload.optBoolean("hybrid")) { ensureNativeHostInitialized(); hybridRecorderSwitchMethod(); }
+                return new JSONObject().put("protocol", 1);
+            case "replay.beginSaveImage":
+                return FTCocosReplayImageJobs.begin(payload);
+            case "replay.pollSaveImage":
+                return FTCocosReplayImageJobs.poll(payload.getString("job"));
+            case "hybrid.setExternalRecorderActive":
+                setExternalRecorderActive(payload.getBoolean("active"));
+                return null;
+            case "replay.configure":
+                configureReplay(payload);
+                return null;
+            case "replay.getContext":
+                return SessionReplayManager.get().getCurrentFlutterRumContext();
+            case "replay.saveImage":
+                return saveReplayImage(payload);
+            case "replay.saveImageV2":
+                return saveReplayImageV2(payload);
+            case "replay.writeSegment":
+                SessionReplayManager.get().writeExternalSegment(
+                        payload.getString("segment"), payload.getString("viewId"));
+                return null;
+            case "replay.setRecordCount":
+                SessionReplayManager.get().setExternalRecordCount(
+                        payload.getString("viewId"), payload.getLong("count"));
+                return null;
+            case "replay.stop":
+                return null;
+            default:
+                throw new IllegalArgumentException("Unknown bridge method: " + method);
+        }
+    }
+
+    private static void ensureNativeHostInitialized() {
+        if (FTSdk.get() == null) {
+            throw new IllegalStateException(
+                    "The native host must install the native SDK before FTCocosSDK.attach()");
+        }
+    }
+
+    private static Method hybridRecorderSwitchMethod() {
+        try {
+            return SessionReplayManager.class.getMethod(
+                    "setExternalRecorderActive", boolean.class);
+        } catch (NoSuchMethodException error) {
+            throw new IllegalStateException(
+                    "Android Session Replay does not support Hybrid recorder switching; "
+                            + "upgrade the Native SDK");
+        }
+    }
+
+    private static void setExternalRecorderActive(boolean active) throws Exception {
+        ensureNativeHostInitialized();
+        try {
+            hybridRecorderSwitchMethod().invoke(SessionReplayManager.get(), active);
+        } catch (InvocationTargetException error) {
+            Throwable cause = error.getCause();
+            if (cause instanceof Exception) throw (Exception) cause;
+            throw error;
+        }
+    }
+
+    private static void configureReplay(JSONObject json) throws Exception {
+        FTSessionReplayConfig config = new FTSessionReplayConfig();
+        if (json.has("sampleRate")) config.setSampleRate((float) json.getDouble("sampleRate"));
+        if (json.has("sessionOnErrorSampleRate")) config.setSessionReplayOnErrorSampleRate((float) json.getDouble("sessionOnErrorSampleRate"));
+        if ("show".equals(json.optString("touchPrivacy"))) config.setTouchPrivacy(TouchPrivacy.SHOW);
+        config.setInternalCallback(new SessionReplayInternalCallback() {
+            @Override public Activity getCurrentActivity() { return FTBridgeTransport.resolveActivity(); }
+        });
+        Method externalMode = FTSessionReplayConfig.class.getDeclaredMethod("setExternalRecorderMode", boolean.class);
+        externalMode.setAccessible(true);
+        externalMode.invoke(config, true);
+        FTSdk.initSessionReplayConfig(config);
+    }
+
+    private static String saveReplayImage(JSONObject json) throws Exception {
+        byte[] bytes = readFile(new File(json.getString("path")));
+        return SessionReplayManager.get().saveFlutterImageResource(bytes, json.getInt("width"), json.getInt("height"));
+    }
+
+    private static Object saveReplayImageV2(JSONObject json) throws Exception {
+        byte[] bytes = readFile(new File(json.getString("path")));
+        Method method;
+        try {
+            method = SessionReplayManager.class.getMethod(
+                    "saveExternalImageResourceV2",
+                    byte[].class,
+                    int.class,
+                    int.class,
+                    float.class,
+                    int.class);
+        } catch (NoSuchMethodException unavailable) {
+            throw new IllegalArgumentException("Unknown bridge method: replay.saveImageV2");
+        }
+        try {
+            return method.invoke(
+                    SessionReplayManager.get(),
+                    bytes,
+                    json.getInt("width"),
+                    json.getInt("height"),
+                    (float) json.optDouble("quality", 0.45),
+                    json.optInt("maxFrameBytes", 40 * 1024));
+        } catch (InvocationTargetException error) {
+            Throwable cause = error.getCause();
+            if (cause instanceof Exception) throw (Exception) cause;
+            throw error;
+        }
+    }
+
+    private static byte[] readFile(File file) throws Exception {
+        FileInputStream input = new FileInputStream(file);
+        try {
+            ByteArrayOutputStream output = new ByteArrayOutputStream((int) Math.min(file.length(), Integer.MAX_VALUE));
+            byte[] buffer = new byte[16 * 1024];
+            int read;
+            while ((read = input.read(buffer)) >= 0) output.write(buffer, 0, read);
+            return output.toByteArray();
+        } finally {
+            input.close();
+        }
+    }}

package/native/android/src/main/java/com/ft/sdk/cocos/FTCocosReplayImageJobs.java

@@ -0,0 +1,55 @@
+package com.ft.sdk.cocos;
+
+import org.json.JSONObject;
+import java.util.UUID;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+
+/** One image in flight across JS runtimes; the caller polls without waiting on disk/encoding. */
+final class FTCocosReplayImageJobs {
+    private static final ExecutorService worker = Executors.newSingleThreadExecutor(runnable -> {
+        Thread thread = new Thread(runnable, "cocos-replay-image");
+        thread.setDaemon(true);
+        return thread;
+    });
+    private static Job current;
+
+    private static final class Job {
+        final String id = UUID.randomUUID().toString();
+        String response;
+    }
+
+    static synchronized String begin(JSONObject arguments) throws Exception {
+        final String method = arguments.getString("method");
+        if (!"replay.saveImage".equals(method) && !"replay.saveImageV2".equals(method)) {
+            throw new IllegalArgumentException("Unsupported asynchronous Replay method");
+        }
+        final String payload = arguments.getJSONObject("arguments").toString();
+        if (current != null && current.response == null) throw new IllegalStateException("Replay encoder is busy");
+        final Job job = new Job();
+        current = job;
+        try {
+            worker.execute(() -> {
+                String response = FTCocosReplayBridge.invokeLocal(method, payload);
+                synchronized (FTCocosReplayImageJobs.class) {
+                    job.response = response;
+                }
+            });
+        } catch (RuntimeException error) {
+            current = null;
+            throw error;
+        }
+        return job.id;
+    }
+
+    static synchronized JSONObject poll(String id) throws Exception {
+        if (current == null || !current.id.equals(id)) throw new IllegalArgumentException("Replay encoding job is unavailable");
+        JSONObject result = new JSONObject();
+        result.put("pending", current.response == null);
+        if (current.response != null) {
+            result.put("response", current.response);
+            current = null;
+        }
+        return result;
+    }
+}

package/native/ios/FTCocosReplayBridge.h

@@ -0,0 +1,10 @@
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/** Cocos JSB reflection entry point. */
+@interface FTCocosReplayBridge : NSObject
++ (NSString *)invoke:(NSString *)method payload:(NSString *)payload;
+@end
+
+NS_ASSUME_NONNULL_END

package/native/ios/FTCocosReplayBridge.m

@@ -0,0 +1,275 @@
+#import "FTCocosReplayBridge.h"
+#import "FTCocosReplayImageJobs.h"
+#import "FTMobileAgent.h"
+#import "FTSessionReplay.h"
+#import <UIKit/UIKit.h>
+#import <objc/message.h>
+
+@implementation FTCocosReplayBridge
+
++ (NSString *)invoke:(NSString *)method payload:(NSString *)payload {
+    @try {
+        NSData *data = [payload dataUsingEncoding:NSUTF8StringEncoding];
+        NSDictionary *arguments = data.length > 0
+            ? [NSJSONSerialization JSONObjectWithData:data options:0 error:nil]
+            : @{};
+        if (![arguments isKindOfClass:NSDictionary.class]) {
+            return [self responseWithValue:nil error:@"Payload must be a JSON object"];
+        }
+        id value = [self dispatch:method arguments:arguments];
+        return [self responseWithValue:value error:nil];
+    } @catch (NSException *exception) {
+        return [self responseWithValue:nil error:[NSString stringWithFormat:@"%@: %@", exception.name, exception.reason ?: @"unknown error"]];
+    }
+}
+
++ (id)dispatch:(NSString *)method arguments:(NSDictionary *)arguments {
+    if ([method isEqualToString:@"replay.capabilities"]) {
+        [self ensureExternalReplayAPIForConfig:[[FTSessionReplayConfig alloc] init]];
+        if ([arguments[@"hybrid"] boolValue]) { [self ensureNativeHostInitialized]; [self ensureHybridRecorderSwitch]; }
+        return @{ @"protocol": @1 };
+    }
+    if ([method isEqualToString:@"replay.beginSaveImage"]) return [self beginSaveImage:arguments];
+    if ([method isEqualToString:@"replay.pollSaveImage"]) {
+        return [FTCocosReplayImageJobs poll:[self requiredText:arguments key:@"job"]];
+    }
+    if ([method isEqualToString:@"hybrid.setExternalRecorderActive"]) {
+        [self ensureNativeHostInitialized];
+        [self setExternalRecorderActive:[arguments[@"active"] boolValue]];
+        return nil;
+    }
+    if ([method isEqualToString:@"replay.configure"]) {
+        FTSessionReplayConfig *config = [[FTSessionReplayConfig alloc] init];
+        [self ensureExternalReplayAPIForConfig:config];
+        if (arguments[@"sampleRate"]) config.sampleRate = [self percent:arguments[@"sampleRate"]];
+        if (arguments[@"sessionOnErrorSampleRate"]) config.sessionReplayOnErrorSampleRate = [self percent:arguments[@"sessionOnErrorSampleRate"]];
+        if ([[self text:arguments[@"touchPrivacy"]] isEqualToString:@"show"]) config.touchPrivacy = FTTouchPrivacyLevelShow;
+        SEL externalMode = NSSelectorFromString(@"setExternalRecorderMode:");
+        ((void (*)(id, SEL, BOOL))objc_msgSend)(config, externalMode, YES);
+        [[FTRumSessionReplay sharedInstance] startWithSessionReplayConfig:config];
+        return nil;
+    }
+    if ([method isEqualToString:@"replay.getContext"]) {
+        return [self invokeReplayObjectSelector:NSSelectorFromString(@"currentExternalRUMContext")];
+    }
+    if ([method isEqualToString:@"replay.saveImage"]) {
+        NSData *rgba = [NSData dataWithContentsOfFile:[self requiredText:arguments key:@"path"]];
+        if (!rgba) [self fail:@"Unable to read replay RGBA file"];
+        NSData *png = [self pngDataFromRGBA:rgba
+                                      width:[arguments[@"width"] unsignedIntegerValue]
+                                     height:[arguments[@"height"] unsignedIntegerValue]];
+        if (!png) [self fail:@"Unable to encode replay image"];
+        return [self invokeReplayObjectSelector:NSSelectorFromString(@"saveExternalImageResourceData:mimeType:")
+                                           first:png
+                                          second:@"image/png"];
+    }
+    if ([method isEqualToString:@"replay.saveImageV2"]) {
+        NSUInteger width = [arguments[@"width"] unsignedIntegerValue];
+        NSUInteger height = [arguments[@"height"] unsignedIntegerValue];
+        NSData *rgba = [NSData dataWithContentsOfFile:[self requiredText:arguments key:@"path"]];
+        if (!rgba) [self fail:@"Unable to read replay RGBA file"];
+        UIImage *image = [self imageFromRGBA:rgba width:width height:height];
+        if (!image) [self fail:@"Unable to decode replay RGBA image"];
+
+        CGFloat quality = MIN(1.0, MAX(0.1, [arguments[@"quality"] doubleValue] ?: 0.45));
+        NSUInteger maxFrameBytes = [arguments[@"maxFrameBytes"] unsignedIntegerValue] ?: 40 * 1024;
+        UIImage *encodedImage = [self opaqueImageFromImage:image size:CGSizeMake(width, height)];
+        NSData *jpeg = UIImageJPEGRepresentation(encodedImage, quality);
+        if (jpeg.length > maxFrameBytes) {
+            quality = MAX(0.2, quality * 0.7);
+            jpeg = UIImageJPEGRepresentation(encodedImage, quality);
+        }
+        if (jpeg.length > maxFrameBytes && width > 1 && height > 1) {
+            width = MAX(1, (NSUInteger)floor(width * 0.75));
+            height = MAX(1, (NSUInteger)floor(height * 0.75));
+            encodedImage = [self opaqueImageFromImage:image size:CGSizeMake(width, height)];
+            jpeg = UIImageJPEGRepresentation(encodedImage, quality);
+        }
+        if (!jpeg || jpeg.length > maxFrameBytes) return @{ @"accepted": @NO };
+
+        NSString *resourceID = [self invokeReplayObjectSelector:NSSelectorFromString(@"saveExternalImageResourceData:mimeType:")
+                                                          first:jpeg
+                                                         second:@"image/jpeg"];
+        if (resourceID.length == 0) [self fail:@"Unable to save replay image resource"];
+        return @{
+            @"accepted": @YES,
+            @"resourceId": resourceID,
+            @"byteSize": @(jpeg.length),
+            @"width": @(width),
+            @"height": @(height),
+            @"mimeType": @"image/jpeg",
+        };
+    }
+    if ([method isEqualToString:@"replay.writeSegment"]) {
+        [self invokeReplayVoidSelector:NSSelectorFromString(@"writeExternalSegment:viewID:")
+                                first:[self requiredText:arguments key:@"segment"]
+                               second:[self requiredText:arguments key:@"viewId"]];
+        return nil;
+    }
+    if ([method isEqualToString:@"replay.setRecordCount"]) {
+        [self invokeReplayCountSelector:NSSelectorFromString(@"setExternalRecordCountForViewID:count:")
+                                 viewID:[self requiredText:arguments key:@"viewId"]
+                                  count:[arguments[@"count"] unsignedIntegerValue]];
+        return nil;
+    }
+    if ([method isEqualToString:@"replay.stop"]) return nil;
+    [self fail:[NSString stringWithFormat:@"Unknown bridge method: %@", method]];
+    return nil;
+}
+
++ (NSString *)beginSaveImage:(NSDictionary *)arguments {
+    NSString *method = [self requiredText:arguments key:@"method"];
+    if (![method isEqualToString:@"replay.saveImage"] && ![method isEqualToString:@"replay.saveImageV2"]) {
+        [self fail:@"Unsupported asynchronous Replay method"];
+    }
+    NSDictionary *payload = [[self dictionary:arguments[@"arguments"]] copy];
+    if (!payload) [self fail:@"Replay image arguments are required"];
+    return [FTCocosReplayImageJobs beginWithWork:^NSString *{
+        return [self responseWithValue:[self dispatch:method arguments:payload] error:nil];
+    }];
+}
+
++ (void)ensureHybridRecorderSwitch {
+    SEL selector = NSSelectorFromString(@"setExternalRecorderActive:");
+    if (![[FTRumSessionReplay sharedInstance] respondsToSelector:selector]) {
+        [self fail:@"iOS Session Replay does not support Hybrid recorder switching; upgrade the Native SDK"];
+    }
+}
+
++ (void)setExternalRecorderActive:(BOOL)active {
+    [self ensureHybridRecorderSwitch];
+    SEL selector = NSSelectorFromString(@"setExternalRecorderActive:");
+    ((void (*)(id, SEL, BOOL))objc_msgSend)([FTRumSessionReplay sharedInstance], selector, active);
+}
+
++ (id)invokeReplayObjectSelector:(SEL)selector {
+    id target = [FTRumSessionReplay sharedInstance];
+    if (![target respondsToSelector:selector]) [self missingReplayAPI:selector];
+    return ((id (*)(id, SEL))objc_msgSend)(target, selector);
+}
+
++ (id)invokeReplayObjectSelector:(SEL)selector object:(id)object {
+    id target = [FTRumSessionReplay sharedInstance];
+    if (![target respondsToSelector:selector]) [self missingReplayAPI:selector];
+    return ((id (*)(id, SEL, id))objc_msgSend)(target, selector, object);
+}
+
++ (id)invokeReplayObjectSelector:(SEL)selector first:(id)first second:(id)second {
+    id target = [FTRumSessionReplay sharedInstance];
+    if (![target respondsToSelector:selector]) [self missingReplayAPI:selector];
+    return ((id (*)(id, SEL, id, id))objc_msgSend)(target, selector, first, second);
+}
+
++ (void)invokeReplayVoidSelector:(SEL)selector first:(id)first second:(id)second {
+    id target = [FTRumSessionReplay sharedInstance];
+    if (![target respondsToSelector:selector]) [self missingReplayAPI:selector];
+    ((void (*)(id, SEL, id, id))objc_msgSend)(target, selector, first, second);
+}
+
++ (void)invokeReplayCountSelector:(SEL)selector viewID:(NSString *)viewID count:(NSUInteger)count {
+    id target = [FTRumSessionReplay sharedInstance];
+    if (![target respondsToSelector:selector]) [self missingReplayAPI:selector];
+    ((void (*)(id, SEL, id, NSUInteger))objc_msgSend)(target, selector, viewID, count);
+}
+
++ (void)missingReplayAPI:(SEL)selector {
+    [self fail:[NSString stringWithFormat:@"FTMobileSDK lacks external Session Replay API %@; use the Cocos-compatible iOS SDK release", NSStringFromSelector(selector)]];
+}
+
++ (void)ensureExternalReplayAPIForConfig:(FTSessionReplayConfig *)config {
+    SEL externalMode = NSSelectorFromString(@"setExternalRecorderMode:");
+    if (![config respondsToSelector:externalMode]) [self missingReplayAPI:externalMode];
+
+    id target = [FTRumSessionReplay sharedInstance];
+    NSArray<NSString *> *selectorNames = @[
+        @"currentExternalRUMContext",
+        @"saveExternalImageResourceData:mimeType:",
+        @"writeExternalSegment:viewID:",
+        @"setExternalRecordCountForViewID:count:",
+    ];
+    for (NSString *name in selectorNames) {
+        SEL selector = NSSelectorFromString(name);
+        if (![target respondsToSelector:selector]) [self missingReplayAPI:selector];
+    }
+}
+
++ (NSData *)pngDataFromRGBA:(NSData *)rgba width:(NSUInteger)width height:(NSUInteger)height {
+    UIImage *image = [self imageFromRGBA:rgba width:width height:height];
+    return image ? UIImagePNGRepresentation(image) : nil;
+}
+
++ (UIImage *)imageFromRGBA:(NSData *)rgba width:(NSUInteger)width height:(NSUInteger)height {
+    if (width == 0 || height == 0 || width > NSUIntegerMax / height / 4 || rgba.length < width * height * 4) {
+        return nil;
+    }
+    NSMutableData *pixels = [rgba mutableCopy];
+    CGColorSpaceRef colorSpace = CGColorSpaceCreateDeviceRGB();
+    CGContextRef context = CGBitmapContextCreate(pixels.mutableBytes,
+                                                 width,
+                                                 height,
+                                                 8,
+                                                 width * 4,
+                                                 colorSpace,
+                                                 (CGBitmapInfo)kCGBitmapByteOrderDefault |
+                                                     (CGBitmapInfo)kCGImageAlphaPremultipliedLast);
+    CGColorSpaceRelease(colorSpace);
+    if (!context) return nil;
+    CGImageRef imageRef = CGBitmapContextCreateImage(context);
+    CGContextRelease(context);
+    if (!imageRef) return nil;
+    UIImage *image = [UIImage imageWithCGImage:imageRef];
+    CGImageRelease(imageRef);
+    return image;
+}
+
++ (UIImage *)opaqueImageFromImage:(UIImage *)image size:(CGSize)size {
+    UIGraphicsBeginImageContextWithOptions(size, YES, 1.0);
+    [[UIColor whiteColor] setFill];
+    UIRectFill(CGRectMake(0, 0, size.width, size.height));
+    [image drawInRect:CGRectMake(0, 0, size.width, size.height)];
+    UIImage *opaque = UIGraphicsGetImageFromCurrentImageContext();
+    UIGraphicsEndImageContext();
+    return opaque;
+}
+
++ (void)ensureNativeHostInitialized {
+    @try {
+        if (![FTMobileAgent sharedInstance]) {
+            [self fail:@"The native host must initialize the native SDK before FTCocosSDK.attach()"];
+        }
+    } @catch (__unused NSException *exception) {
+        [self fail:@"The native host must initialize the native SDK before FTCocosSDK.attach()"];
+    }
+}
+
++ (NSString *)responseWithValue:(id)value error:(NSString *)error {
+    NSMutableDictionary *response = [@{ @"ok": @(error == nil) } mutableCopy];
+    if (value) response[@"value"] = value;
+    if (error) response[@"error"] = error;
+    NSData *data = [NSJSONSerialization dataWithJSONObject:response options:0 error:nil];
+    return [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding] ?: @"{\"ok\":false}";
+}
+
++ (NSDictionary *)dictionary:(id)value {
+    return [value isKindOfClass:NSDictionary.class] ? value : nil;
+}
+
++ (NSString *)text:(id)value {
+    return [value isKindOfClass:NSString.class] && [value length] > 0 ? value : nil;
+}
+
++ (NSString *)requiredText:(NSDictionary *)arguments key:(NSString *)key {
+    NSString *value = [self text:arguments[key]];
+    if (value.length == 0) [self fail:[NSString stringWithFormat:@"%@ is required", key]];
+    return value;
+}
+
++ (int)percent:(NSNumber *)number {
+    return (int)lround(MIN(1.0, MAX(0.0, number.doubleValue)) * 100.0);
+}
+
++ (void)fail:(NSString *)message {
+    @throw [NSException exceptionWithName:@"FTCocosBridgeError" reason:message userInfo:nil];
+}
+
+@end

package/native/ios/FTCocosReplayBridge.podspec

@@ -0,0 +1,18 @@
+Pod::Spec.new do |s|
+  s.name             = 'FTCocosReplayBridge'
+  s.version          = '0.1.0-alpha.6'
+  s.summary          = 'CloudCare Mobile SDK native bridge for Cocos Creator.'
+  s.homepage         = 'https://github.com/GuanceCloud/datakit-cocos'
+  s.license          = { :type => 'Apache-2.0' }
+  s.author           = { 'Guance Cloud' => 'support@guance.com' }
+  s.source           = { :path => '.' }
+  s.platform         = :ios, '12.0'
+  s.source_files     = 'FTCocosReplayBridge.{h,m}', 'FTCocosReplayImageJobs.{h,m}'
+  s.public_header_files = 'FTCocosReplayBridge.h'
+  s.requires_arc     = true
+  # Cocos resolves FTCocosReplayBridge by class name at runtime, so no direct symbol
+  # reference would otherwise keep the Objective-C category/class in the app.
+  s.user_target_xcconfig = { 'OTHER_LDFLAGS' => '$(inherited) -ObjC' }
+  s.dependency 'GuanceSDK/FTSessionReplay', '1.6.8-alpha.5'
+  s.dependency 'GuanceSDK/Agent', '1.6.8-alpha.5'
+end

package/native/ios/FTCocosReplayImageJobs.h

@@ -0,0 +1,11 @@
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/** One background image operation, with nonblocking result retrieval from JSB. */
+@interface FTCocosReplayImageJobs : NSObject
++ (NSString *)beginWithWork:(NSString *(^)(void))work;
++ (NSDictionary *)poll:(NSString *)identifier;
+@end
+
+NS_ASSUME_NONNULL_END

package/native/ios/FTCocosReplayImageJobs.m

@@ -0,0 +1,54 @@
+#import "FTCocosReplayImageJobs.h"
+
+@interface FTCocosReplayImageJob : NSObject
+@property (nonatomic, copy) NSString *identifier;
+@property (nonatomic, copy) NSString *response;
+@end
+@implementation FTCocosReplayImageJob
+@end
+
+static FTCocosReplayImageJob *currentJob;
+
+@implementation FTCocosReplayImageJobs
+
++ (NSString *)beginWithWork:(NSString *(^)(void))work {
+    FTCocosReplayImageJob *job = [FTCocosReplayImageJob new];
+    job.identifier = NSUUID.UUID.UUIDString;
+    @synchronized (self) {
+        if (currentJob && !currentJob.response) {
+            [NSException raise:NSInternalInconsistencyException format:@"Replay encoder is busy"];
+        }
+        currentJob = job;
+    }
+    dispatch_async(dispatch_get_global_queue(QOS_CLASS_UTILITY, 0), ^{
+        @autoreleasepool {
+            NSString *response;
+            @try {
+                response = work();
+            } @catch (NSException *exception) {
+                NSData *data = [NSJSONSerialization dataWithJSONObject:@{
+                    @"ok": @NO, @"error": exception.reason ?: @"Replay encoding failed"
+                } options:0 error:nil];
+                response = [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding];
+            }
+            @synchronized (self) {
+                job.response = response ?: @"{\"ok\":false,\"error\":\"Empty Replay encoding result\"}";
+            }
+        }
+    });
+    return job.identifier;
+}
+
++ (NSDictionary *)poll:(NSString *)identifier {
+    @synchronized (self) {
+        if (![currentJob.identifier isEqualToString:identifier]) {
+            [NSException raise:NSInvalidArgumentException format:@"Replay encoding job is unavailable"];
+        }
+        if (!currentJob.response) return @{ @"pending": @YES };
+        NSDictionary *result = @{ @"pending": @NO, @"response": currentJob.response };
+        currentJob = nil;
+        return result;
+    }
+}
+
+@end

package/native/ios/Package.swift

@@ -0,0 +1,26 @@
+// swift-tools-version:5.3
+import PackageDescription
+
+let package = Package(
+    name: "FTCocosReplayBridge",
+    platforms: [.iOS(.v12)],
+    products: [.library(name: "FTCocosReplayBridge", targets: ["FTCocosReplayBridge"])],
+    dependencies: [
+        .package(url: "https://github.com/GuanceCloud/datakit-ios.git", .exact("1.6.8-alpha.5")),
+    ],
+    targets: [
+        .target(
+            name: "FTCocosReplayBridge",
+            dependencies: [
+                .product(name: "GuanceSDK", package: "datakit-ios"),
+                .product(name: "GuanceSessionReplay", package: "datakit-ios"),
+            ],
+            path: ".",
+            exclude: ["FTCocosReplayBridge.podspec"],
+            sources: ["FTCocosReplayBridge.m", "FTCocosReplayImageJobs.m"],
+            publicHeadersPath: "include",
+            cSettings: [.headerSearchPath(".")],
+            linkerSettings: [.linkedFramework("UIKit")]
+        ),
+    ]
+)

package/native/ios/include/FTCocosReplayBridge.h

@@ -0,0 +1,10 @@
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/** Cocos JSB reflection entry point. */
+@interface FTCocosReplayBridge : NSObject
++ (NSString *)invoke:(NSString *)method payload:(NSString *)payload;
+@end
+
+NS_ASSUME_NONNULL_END