cloudx-react-native 3.4.6 → 3.6.0

package/ios/CloudXAdView.mm

@@ -0,0 +1,500 @@
+//
+//  CloudXAdView.mm
+//  cloudx-react-native
+//
+
+#import "CloudXAdView.h"
+#import "CloudXExtraParameters.h"
+#import <React/RCTLog.h>
+
+#ifdef RCT_NEW_ARCH_ENABLED
+#import <react/renderer/components/CloudXSpec/ComponentDescriptors.h>
+#import <react/renderer/components/CloudXSpec/EventEmitters.h>
+#import <react/renderer/components/CloudXSpec/Props.h>
+#import <react/renderer/components/CloudXSpec/RCTComponentViewHelpers.h>
+#import <React/RCTConversions.h>
+#import "RCTFabricComponentsPlugins.h"
+
+using namespace facebook::react;
+
+/*
+ * Fills a generated AdInfo-style event struct from the NSDictionary the ad
+ * delegate builds. All three ad-info events share the same field set, so this
+ * macro keeps the three emitter blocks in sync.
+ */
+#define CLX_FILL_ADINFO(result, event) \
+    result.adUnitId         = std::string([(event[@"adUnitId"] ?: @"") UTF8String]); \
+    result.adFormat         = std::string([(event[@"adFormat"] ?: @"") UTF8String]); \
+    result.networkName      = std::string([(event[@"networkName"] ?: @"") UTF8String]); \
+    result.networkPlacement = std::string([(event[@"networkPlacement"] ?: @"") UTF8String]); \
+    result.placement        = std::string([(event[@"placement"] ?: @"") UTF8String]); \
+    result.revenue          = [event[@"revenue"] doubleValue]; \
+    result.adValuesJson     = std::string([(event[@"adValuesJson"] ?: @"") UTF8String]);
+
+static id CLXIdFromFollyDynamic(const folly::dynamic &dynamicValue)
+{
+    switch ( dynamicValue.type() )
+    {
+        case folly::dynamic::NULLT:
+            return [NSNull null];
+        case folly::dynamic::BOOL:
+            return @(dynamicValue.getBool());
+        case folly::dynamic::INT64:
+            return @(dynamicValue.getInt());
+        case folly::dynamic::DOUBLE:
+            return @(dynamicValue.getDouble());
+        case folly::dynamic::STRING:
+            return [[NSString alloc] initWithBytes: dynamicValue.c_str() length: dynamicValue.size() encoding: NSUTF8StringEncoding] ?: @"";
+        case folly::dynamic::ARRAY: {
+            NSMutableArray *array = [NSMutableArray arrayWithCapacity: dynamicValue.size()];
+            for ( const auto &item : dynamicValue )
+            {
+                [array addObject: CLXIdFromFollyDynamic(item) ?: [NSNull null]];
+            }
+            return [array copy];
+        }
+        case folly::dynamic::OBJECT: {
+            NSMutableDictionary<NSString *, id> *dictionary = [NSMutableDictionary dictionaryWithCapacity: dynamicValue.size()];
+            for ( const auto &item : dynamicValue.items() )
+            {
+                id key = CLXIdFromFollyDynamic(item.first);
+                if ( ![key isKindOfClass: [NSString class]] ) continue;
+                dictionary[key] = CLXIdFromFollyDynamic(item.second) ?: [NSNull null];
+            }
+            return [dictionary copy];
+        }
+    }
+
+    return [NSNull null];
+}
+
+@interface CloudXAdView () <RCTCloudXAdViewViewProtocol>
+#else
+@interface CloudXAdView ()
+#endif
+
+@property (nonatomic, strong, nullable) CLXBannerAdView *adView;
+@property (nonatomic, copy, nullable) NSString *adUnitId;
+@property (nonatomic, copy, nullable) NSString *adFormat;
+@property (nonatomic, copy, nullable) NSString *placement;
+@property (nonatomic, copy, nullable) NSString *customData;
+@property (nonatomic, copy) NSDictionary<NSString *, id> *extraParameters;
+@property (nonatomic, copy) NSSet<NSString *> *appliedExtraParameterKeys;
+
+@end
+
+@implementation CloudXAdView
+
+- (void)commonInit
+{
+    _extraParameters = @{};
+    _appliedExtraParameterKeys = [NSSet set];
+}
+
+#ifdef RCT_NEW_ARCH_ENABLED
+
++ (ComponentDescriptorProvider)componentDescriptorProvider
+{
+    return concreteComponentDescriptorProvider<CloudXAdViewComponentDescriptor>();
+}
+
+- (instancetype)initWithFrame:(CGRect)frame
+{
+    self = [super initWithFrame: frame];
+    if ( self )
+    {
+        [self commonInit];
+        static const auto defaultProps = std::make_shared<const CloudXAdViewProps>();
+        _props = defaultProps;
+        [self setupEventHandlers];
+    }
+    return self;
+}
+
+/*
+ * On Fabric the RCTDirectEventBlock properties are not wired by a view manager,
+ * so point each block at the generated C++ EventEmitter. The delegate callbacks
+ * below always call self.onXxxEvent(dict) regardless of architecture.
+ */
+- (void)setupEventHandlers
+{
+    __weak CloudXAdView *weakSelf = self;
+
+    self.onAdLoadedEvent = ^(NSDictionary *event) {
+        CloudXAdView *strongSelf = weakSelf;
+        if ( !strongSelf || !strongSelf->_eventEmitter ) return;
+        auto emitter = std::static_pointer_cast<CloudXAdViewEventEmitter const>(strongSelf->_eventEmitter);
+        CloudXAdViewEventEmitter::OnAdLoadedEvent result;
+        CLX_FILL_ADINFO(result, event);
+        emitter->onAdLoadedEvent(result);
+    };
+
+    self.onAdClickedEvent = ^(NSDictionary *event) {
+        CloudXAdView *strongSelf = weakSelf;
+        if ( !strongSelf || !strongSelf->_eventEmitter ) return;
+        auto emitter = std::static_pointer_cast<CloudXAdViewEventEmitter const>(strongSelf->_eventEmitter);
+        CloudXAdViewEventEmitter::OnAdClickedEvent result;
+        CLX_FILL_ADINFO(result, event);
+        emitter->onAdClickedEvent(result);
+    };
+
+    self.onAdRevenuePaidEvent = ^(NSDictionary *event) {
+        CloudXAdView *strongSelf = weakSelf;
+        if ( !strongSelf || !strongSelf->_eventEmitter ) return;
+        auto emitter = std::static_pointer_cast<CloudXAdViewEventEmitter const>(strongSelf->_eventEmitter);
+        CloudXAdViewEventEmitter::OnAdRevenuePaidEvent result;
+        CLX_FILL_ADINFO(result, event);
+        emitter->onAdRevenuePaidEvent(result);
+    };
+
+    self.onAdLoadFailedEvent = ^(NSDictionary *event) {
+        CloudXAdView *strongSelf = weakSelf;
+        if ( !strongSelf || !strongSelf->_eventEmitter ) return;
+        auto emitter = std::static_pointer_cast<CloudXAdViewEventEmitter const>(strongSelf->_eventEmitter);
+        CloudXAdViewEventEmitter::OnAdLoadFailedEvent result;
+        result.adUnitId = std::string([(event[@"adUnitId"] ?: @"") UTF8String]);
+        result.code     = [event[@"code"] doubleValue];
+        result.message  = std::string([(event[@"message"] ?: @"") UTF8String]);
+        emitter->onAdLoadFailedEvent(result);
+    };
+}
+
+- (void)updateProps:(Props::Shared const &)props oldProps:(Props::Shared const &)oldProps
+{
+    const auto &oldViewProps = *std::static_pointer_cast<CloudXAdViewProps const>(_props);
+    const auto &newViewProps = *std::static_pointer_cast<CloudXAdViewProps const>(props);
+
+    BOOL shouldAttach = NO;
+
+    if ( oldViewProps.adUnitId != newViewProps.adUnitId )
+    {
+        [self setAdUnitId: RCTNSStringFromString(newViewProps.adUnitId)];
+        shouldAttach = YES;
+    }
+    if ( oldViewProps.adFormat != newViewProps.adFormat )
+    {
+        [self setAdFormat: RCTNSStringFromString(newViewProps.adFormat)];
+    }
+    if ( oldViewProps.placement != newViewProps.placement )
+    {
+        [self setPlacement: RCTNSStringFromStringNilIfEmpty(newViewProps.placement)];
+    }
+    if ( oldViewProps.customData != newViewProps.customData )
+    {
+        [self setCustomData: RCTNSStringFromStringNilIfEmpty(newViewProps.customData)];
+    }
+    /*
+     * CloudXAdViewExtraParametersStruct contains folly::dynamic, so the
+     * generated props do not support a simple old/new equality guard like the
+     * scalar props above. Applying is idempotent, with removed keys cleared by
+     * applyExtraParametersIfReady.
+     */
+    [self setExtraParametersFromEntryArray: [self entryArrayFromFabricExtraParameters: newViewProps.extraParameters]];
+
+    if ( shouldAttach )
+    {
+        [self attachAdViewIfNeeded];
+    }
+
+    [super updateProps: props oldProps: oldProps];
+}
+
+- (void)prepareForRecycle
+{
+    [super prepareForRecycle];
+
+    static const auto defaultProps = std::make_shared<const CloudXAdViewProps>();
+    _props = defaultProps;
+
+    [self destroyAdIfNeeded];
+    self.adUnitId = nil;
+    self.adFormat = nil;
+    self.placement = nil;
+    self.customData = nil;
+    self.extraParameters = @{};
+    self.appliedExtraParameterKeys = [NSSet set];
+}
+
+- (NSArray<NSDictionary<NSString *, id> *> *)entryArrayFromFabricExtraParameters:(const std::vector<CloudXAdViewExtraParametersStruct> &)entries
+{
+    NSMutableArray<NSDictionary<NSString *, id> *> *result = [NSMutableArray arrayWithCapacity: entries.size()];
+    for ( const auto &entry : entries )
+    {
+        NSString *key = [NSString stringWithUTF8String: entry.key.c_str()] ?: @"";
+        id value = CLXIdFromFollyDynamic(entry.value) ?: [NSNull null];
+        [result addObject: @{@"key": key, @"value": value}];
+    }
+    return [result copy];
+}
+
+#else
+
+- (instancetype)init
+{
+    self = [super init];
+    if ( self )
+    {
+        [self commonInit];
+    }
+    return self;
+}
+
+#endif // RCT_NEW_ARCH_ENABLED
+
+#pragma mark - Property setters (shared; Paper view manager sets these via KVC)
+
+- (void)setAdUnitId:(NSString *)adUnitId
+{
+    if ( self.adView )
+    {
+        // Ad unit ID is immutable once the ad view is created. Warn only on an
+        // actual change; unchanged re-sets on re-render stay quiet.
+        if ( ![adUnitId isEqualToString: _adUnitId] )
+        {
+            RCTLogWarn(@"CloudXAdView: adUnitId cannot change after the ad view is created; remount the component (e.g. via a React key).");
+        }
+        return;
+    }
+    _adUnitId = adUnitId;
+}
+
+- (void)setAdFormat:(NSString *)adFormat
+{
+    if ( self.adView )
+    {
+        if ( ![adFormat isEqualToString: _adFormat] )
+        {
+            RCTLogWarn(@"CloudXAdView: adFormat cannot change after the ad view is created; remount the component (e.g. via a React key).");
+        }
+        return;
+    }
+    _adFormat = adFormat;
+}
+
+- (void)setPlacement:(NSString *)placement
+{
+    _placement = placement;
+    self.adView.placement = placement;
+}
+
+- (void)setCustomData:(NSString *)customData
+{
+    _customData = customData;
+    self.adView.customData = customData;
+}
+
+- (void)setExtraParametersFromEntryArray:(nullable NSArray<NSDictionary<NSString *, id> *> *)extraParameters
+{
+    self.extraParameters = [CloudXExtraParameters dictionaryFromEntryArray: extraParameters];
+    [self applyExtraParametersIfReady];
+}
+
+#pragma mark - Paper attach hook
+
+// Invoked after all JS props are set when mounting on the Old Architecture.
+- (void)didSetProps:(NSArray<NSString *> *)changedProps
+{
+    [self attachAdViewIfNeeded];
+}
+
+#pragma mark - Ad view lifecycle
+
+- (void)attachAdViewIfNeeded
+{
+    NSString *adUnitId = self.adUnitId;
+    NSString *adFormat = self.adFormat;
+
+    dispatch_async(dispatch_get_main_queue(), ^{
+        if ( self.adView ) return;
+        if ( adUnitId.length == 0 || adFormat.length == 0 ) return;
+
+        CLXBannerAdView *adView;
+        if ( [adFormat caseInsensitiveCompare: @"MREC"] == NSOrderedSame )
+        {
+            adView = [[CloudXCore shared] createMRECWithAdUnitId: adUnitId];
+        }
+        else
+        {
+            adView = [[CloudXCore shared] createBannerWithAdUnitId: adUnitId];
+        }
+
+        if ( !adView )
+        {
+            /*
+             * createBanner/createMRECWithAdUnitId: returned nil. The JS layer
+             * gates mounting on SDK initialization, so a nil here post-init is
+             * an invalid/expired ad unit — surface it as a load failure instead
+             * of leaving a permanently-dead, silent view (self.adView stays nil
+             * and props don't re-land, so there is no retry).
+             */
+            if ( self.onAdLoadFailedEvent )
+            {
+                self.onAdLoadFailedEvent(@{@"adUnitId": adUnitId ?: @"",
+                                           @"code":     @(CLXErrorCodeInvalidAdUnit),
+                                           @"message":  @"Ad view creation returned nil (invalid ad unit or SDK not initialized)"});
+            }
+            return;
+        }
+
+        adView.delegate = self;
+        adView.revenueDelegate = self;
+        adView.placement = self.placement;
+        adView.customData = self.customData;
+        adView.userInteractionEnabled = YES;
+        adView.translatesAutoresizingMaskIntoConstraints = NO;
+
+        self.adView = adView;
+        [self applyExtraParametersIfReady];
+        [self addSubview: adView];
+        [NSLayoutConstraint activateConstraints: @[
+            [adView.topAnchor constraintEqualToAnchor: self.topAnchor],
+            [adView.bottomAnchor constraintEqualToAnchor: self.bottomAnchor],
+            [adView.leadingAnchor constraintEqualToAnchor: self.leadingAnchor],
+            [adView.trailingAnchor constraintEqualToAnchor: self.trailingAnchor],
+        ]];
+
+        [adView load];
+        [self updateAutoRefreshForWindowVisibility];
+    });
+}
+
+- (void)updateAutoRefreshForWindowVisibility
+{
+    if ( !self.adView ) return;
+    if ( self.window )
+    {
+        [self.adView startAutoRefresh];
+    }
+    else
+    {
+        [self.adView stopAutoRefresh];
+    }
+}
+
+- (void)didMoveToWindow
+{
+    [super didMoveToWindow];
+    [self updateAutoRefreshForWindowVisibility];
+}
+
+- (void)didMoveToSuperview
+{
+    [super didMoveToSuperview];
+
+    if ( self.superview != nil )
+    {
+        [self updateAutoRefreshForWindowVisibility];
+        return;
+    }
+
+    // Superview nil could be a real unmount or brief reparenting (react-native-screens).
+    // Defer one main-queue turn; destroy only if it is still detached. Strong ref so the
+    // ad is always torn down on a genuine unmount.
+    CloudXAdView *viewRef = self;
+    dispatch_async(dispatch_get_main_queue(), ^{
+        if ( viewRef.superview != nil )
+        {
+            [viewRef updateAutoRefreshForWindowVisibility];
+            return;
+        }
+        [viewRef destroyAdIfNeeded];
+    });
+}
+
+- (void)dealloc
+{
+    [self destroyAdIfNeeded];
+}
+
+- (void)destroyAdIfNeeded
+{
+    if ( !self.adView ) return;
+
+    [self.adView stopAutoRefresh];
+    self.adView.delegate = nil;
+    self.adView.revenueDelegate = nil;
+    [self.adView destroy];
+    [self.adView removeFromSuperview];
+    self.adView = nil;
+    self.appliedExtraParameterKeys = [NSSet set];
+}
+
+- (void)applyExtraParametersIfReady
+{
+    if ( !self.adView ) return;
+
+    NSDictionary<NSString *, id> *extraParameters = self.extraParameters ?: @{};
+    [CloudXExtraParameters applyExtraParameters: extraParameters toAdView: self.adView logBlock: nil];
+
+    NSMutableDictionary<NSString *, id> *removed = [NSMutableDictionary dictionary];
+    for ( NSString *key in self.appliedExtraParameterKeys )
+    {
+        if ( !extraParameters[key] )
+        {
+            removed[key] = [NSNull null];
+        }
+    }
+    [CloudXExtraParameters applyExtraParameters: removed toAdView: self.adView logBlock: nil];
+    self.appliedExtraParameterKeys = [NSSet setWithArray: extraParameters.allKeys];
+}
+
+#pragma mark - Event payloads
+
+- (NSDictionary<NSString *, id> *)adInfoDictForAd:(CLXAd *)ad
+{
+    NSString *adValuesJson = @"";
+    if ( ad.adValues )
+    {
+        NSData *data = [NSJSONSerialization dataWithJSONObject: ad.adValues options: 0 error: nil];
+        if ( data )
+        {
+            adValuesJson = [[NSString alloc] initWithData: data encoding: NSUTF8StringEncoding] ?: @"";
+        }
+    }
+
+    return @{@"adUnitId":         ad.adUnitId ?: @"",
+             @"adFormat":         self.adFormat ?: @"",
+             @"networkName":      ad.networkName ?: @"",
+             @"networkPlacement": ad.networkPlacement ?: @"",
+             @"placement":        ad.placement ?: @"",
+             @"revenue":          ad.revenue ?: @(0),
+             @"adValuesJson":     adValuesJson};
+}
+
+- (NSDictionary<NSString *, id> *)loadFailedDictForAdUnit:(NSString *)adUnitId error:(CLXError *)error
+{
+    return @{@"adUnitId": adUnitId ?: (self.adUnitId ?: @""),
+             @"code":     error ? @(error.code) : @(CLXErrorCodeInternalError),
+             @"message":  error.localizedDescription ?: @""};
+}
+
+#pragma mark - CLXBannerDelegate / CLXAdRevenueDelegate
+
+- (void)didLoadAd:(CLXAd *)ad
+{
+    if ( self.onAdLoadedEvent ) self.onAdLoadedEvent([self adInfoDictForAd: ad]);
+}
+
+- (void)didFailToLoadAd:(NSString *)adUnitId error:(CLXError *)error
+{
+    if ( self.onAdLoadFailedEvent ) self.onAdLoadFailedEvent([self loadFailedDictForAdUnit: adUnitId error: error]);
+}
+
+- (void)didClickAd:(CLXAd *)ad
+{
+    if ( self.onAdClickedEvent ) self.onAdClickedEvent([self adInfoDictForAd: ad]);
+}
+
+- (void)didPayRevenueForAd:(CLXAd *)ad
+{
+    if ( self.onAdRevenuePaidEvent ) self.onAdRevenuePaidEvent([self adInfoDictForAd: ad]);
+}
+
+@end
+
+#ifdef RCT_NEW_ARCH_ENABLED
+Class<RCTComponentViewProtocol> CloudXAdViewCls(void)
+{
+    return [CloudXAdView class];
+}
+#endif

package/ios/CloudXAdViewManager.h

@@ -0,0 +1,12 @@
+//
+//  CloudXAdViewManager.h
+//  cloudx-react-native
+//
+//  Old-Architecture (Paper) view manager for the in-tree CloudXAdView.
+//
+
+#import <React/RCTViewManager.h>
+
+@interface CloudXAdViewManager : RCTViewManager
+
+@end

package/ios/CloudXAdViewManager.mm

@@ -0,0 +1,38 @@
+//
+//  CloudXAdViewManager.mm
+//  cloudx-react-native
+//
+
+#import "CloudXAdViewManager.h"
+#import "CloudXAdView.h"
+
+@implementation CloudXAdViewManager
+
+RCT_EXPORT_MODULE(CloudXAdView)
+
+RCT_EXPORT_VIEW_PROPERTY(adUnitId, NSString)
+RCT_EXPORT_VIEW_PROPERTY(adFormat, NSString)
+RCT_EXPORT_VIEW_PROPERTY(placement, NSString)
+RCT_EXPORT_VIEW_PROPERTY(customData, NSString)
+RCT_CUSTOM_VIEW_PROPERTY(extraParameters, NSArray, CloudXAdView)
+{
+    NSArray<NSDictionary<NSString *, id> *> *entries = [json isKindOfClass: [NSArray class]] ? json : nil;
+    [view setExtraParametersFromEntryArray: entries];
+}
+
+RCT_EXPORT_VIEW_PROPERTY(onAdLoadedEvent, RCTDirectEventBlock)
+RCT_EXPORT_VIEW_PROPERTY(onAdLoadFailedEvent, RCTDirectEventBlock)
+RCT_EXPORT_VIEW_PROPERTY(onAdClickedEvent, RCTDirectEventBlock)
+RCT_EXPORT_VIEW_PROPERTY(onAdRevenuePaidEvent, RCTDirectEventBlock)
+
++ (BOOL)requiresMainQueueSetup
+{
+    return YES;
+}
+
+- (UIView *)view
+{
+    return [[CloudXAdView alloc] init];
+}
+
+@end

package/ios/CloudXExtraParameters.h

@@ -0,0 +1,27 @@
+/*
+ * CloudXExtraParameters.h
+ * cloudx-react-native
+ */
+
+#import <Foundation/Foundation.h>
+#import <CloudXCore/CloudXCore.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+typedef void (^CloudXExtraParametersLogBlock)(NSString *message);
+
+@interface CloudXExtraParameters : NSObject
+
++ (NSDictionary<NSString *, id> *)dictionaryFromEntryArray:(nullable NSArray<NSDictionary<NSString *, id> *> *)entries;
++ (void)mergeExtraParameters:(NSDictionary<NSString *, id> *)extraParameters
+       intoPendingDictionary:(NSMutableDictionary<NSString *, id> *)pending;
++ (void)applyExtraParameters:(NSDictionary<NSString *, id> *)extraParameters
+                   toAdView:(CLXBannerAdView *)adView
+                  logBlock:(nullable CloudXExtraParametersLogBlock)logBlock;
++ (void)applyExtraParameters:(NSDictionary<NSString *, id> *)extraParameters
+             toFullscreenAd:(id<CLXFullscreenAd>)ad
+                  logBlock:(nullable CloudXExtraParametersLogBlock)logBlock;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/CloudXExtraParameters.mm

@@ -0,0 +1,117 @@
+/*
+ * CloudXExtraParameters.mm
+ * cloudx-react-native
+ */
+
+#import "CloudXExtraParameters.h"
+
+@implementation CloudXExtraParameters
+
++ (NSDictionary<NSString *, id> *)dictionaryFromEntryArray:(nullable NSArray<NSDictionary<NSString *, id> *> *)entries
+{
+    if ( !entries || ![(id)entries isKindOfClass: [NSArray class]] )
+    {
+        return @{};
+    }
+
+    NSMutableDictionary<NSString *, id> *extraParameters = [NSMutableDictionary dictionary];
+    for ( id entry in entries )
+    {
+        if ( ![entry isKindOfClass: [NSDictionary class]] ) continue;
+
+        NSDictionary<NSString *, id> *entryDictionary = (NSDictionary<NSString *, id> *)entry;
+        id keyValue = entryDictionary[@"key"];
+        if ( ![keyValue isKindOfClass: [NSString class]] ) continue;
+
+        NSString *key = (NSString *)keyValue;
+        if ( key.length == 0 ) continue;
+
+        extraParameters[key] = entryDictionary[@"value"] ?: [NSNull null];
+    }
+
+    return [extraParameters copy];
+}
+
++ (void)mergeExtraParameters:(NSDictionary<NSString *, id> *)extraParameters
+       intoPendingDictionary:(NSMutableDictionary<NSString *, id> *)pending
+{
+    [extraParameters enumerateKeysAndObjectsUsingBlock:^(NSString *key, id value, BOOL *stop) {
+        if ( !key || key.length == 0 ) return;
+        if ( !value || [value isKindOfClass: [NSNull class]] )
+        {
+            [pending removeObjectForKey: key];
+        }
+        else
+        {
+            pending[key] = value;
+        }
+    }];
+}
+
++ (void)applyExtraParameters:(NSDictionary<NSString *, id> *)extraParameters
+                   toAdView:(CLXBannerAdView *)adView
+                  logBlock:(nullable CloudXExtraParametersLogBlock)logBlock
+{
+    SEL selector = NSSelectorFromString(@"setExtraParameter:value:");
+    id target = [adView respondsToSelector: selector] ? adView : adView.ad;
+
+    [extraParameters enumerateKeysAndObjectsUsingBlock:^(NSString *key, id value, BOOL *stop) {
+        if ( !key || key.length == 0 ) return;
+        id normalizedValue = [value isKindOfClass: [NSNull class]] ? nil : value;
+        [self applyExtraParameterValue: normalizedValue forKey: key toTarget: target logBlock: logBlock];
+    }];
+}
+
++ (void)applyExtraParameters:(NSDictionary<NSString *, id> *)extraParameters
+             toFullscreenAd:(id<CLXFullscreenAd>)ad
+                  logBlock:(nullable CloudXExtraParametersLogBlock)logBlock
+{
+    [extraParameters enumerateKeysAndObjectsUsingBlock:^(NSString *key, id value, BOOL *stop) {
+        if ( !key || key.length == 0 ) return;
+        id normalizedValue = [value isKindOfClass: [NSNull class]] ? nil : value;
+        [self applyExtraParameterValue: normalizedValue forKey: key toTarget: ad logBlock: logBlock];
+    }];
+}
+
++ (void)applyExtraParameterValue:(id)value
+                         forKey:(NSString *)key
+                       toTarget:(id)target
+                       logBlock:(nullable CloudXExtraParametersLogBlock)logBlock
+{
+    if ( !target || !key || key.length == 0 ) return;
+
+    SEL selector = NSSelectorFromString(@"setExtraParameter:value:");
+    if ( ![target respondsToSelector: selector] )
+    {
+        selector = NSSelectorFromString(@"setExtraParameterForKey:value:");
+    }
+
+    if ( ![target respondsToSelector: selector] )
+    {
+        if ( logBlock )
+        {
+            logBlock(
+                [NSString stringWithFormat: @"Skipping extra parameter \"%@\" because %@ does not respond to setExtraParameter:value: or setExtraParameterForKey:value:",
+                                           key,
+                                           NSStringFromClass([target class])]
+            );
+        }
+        return;
+    }
+
+    using SetExtraParameterMethod = void (*)(id, SEL, NSString *, id);
+    SetExtraParameterMethod method = (SetExtraParameterMethod)[target methodForSelector: selector];
+    method(target, selector, key, value);
+
+    if ( logBlock )
+    {
+        logBlock(
+            [NSString stringWithFormat: @"Applied extra parameter \"%@\" with value \"%@\" to %@",
+                                       key,
+                                       value ?: @"(cleared)",
+                                       NSStringFromClass([target class])]
+        );
+    }
+}
+
+@end