diff --git a/.circleci/config.yml b/.circleci/config.yml index 4f7a19ed3..e45bb6321 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -41,7 +41,6 @@ jobs: name: Run Smoke UI Tests command: scripts/testPrebidDemo.sh -ui -l - workflows: pr-check: jobs: diff --git a/.github/workflows/upload-docs-ios.yml b/.github/workflows/upload-docs-ios.yml new file mode 100644 index 000000000..8afe7b82d --- /dev/null +++ b/.github/workflows/upload-docs-ios.yml @@ -0,0 +1,58 @@ +name: Upload Docs iOS + +on: + push: + tags: + - '[0-9]+.[0-9]+.[0-9]+' + - 'test-doc-*' + +jobs: + upload-docs: + + runs-on: macos-latest + + steps: + - name: Checkout current branch + uses: actions/checkout@v4 + - name: Install Jazzy + run: | + gem install jazzy + - name: Generate docs + run: | + jazzy + cp -r docs docs_new + - name: Checkout docs branch + uses: actions/checkout@v4 + with: + fetch-depth: 0 + ref: docs + clean: false + - name: Commit documentation changes + run: | + MIN_SIZE=5120 + if [ -d docs_new ] && [ "$(du -s docs_new | cut -f1)" -ge "$MIN_SIZE" ]; then + rm -rf docs + cp -r docs_new docs + rm -rf docs_new + else + echo "docs_new directory either does not exist or is too small." + exit 1 + fi + + if [ "$(git status --porcelain | wc -l)" -gt 0 ]; then + git config --local user.email "41898282+github-actions[bot]@users.noreply.github.com" + git config --local user.name "github-actions[bot]" + git status + TAG_NAME=${{ github.ref }} + TAG_NAME=${TAG_NAME#refs/tags/} + echo "Current tag: $TAG_NAME" + git add docs + git commit -m "Generate docs - $TAG_NAME" + else + echo "No changes to commit." + fi + - name: Push changes + uses: ad-m/github-push-action@master + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + branch: docs diff --git a/.jazzy.yaml b/.jazzy.yaml new file mode 100644 index 000000000..4f3d949f5 --- /dev/null +++ b/.jazzy.yaml @@ -0,0 +1,63 @@ +# Ordered by output of `jazzy — help config` +output: docs +clean: true +xcodebuild_arguments: +- -workspace +- PrebidMobile.xcworkspace +- -scheme +- PrebidMobile +- CODE_SIGNING_ALLOWED = NO +author: Prebid +readme: README_API_DOC.md +exclude: + - PrebidMobile/Addendum/* + - PrebidMobile/AdUnits/BannerBasedAdUnitProtocol.swift + - PrebidMobile/AdUnits/VideoBasedAdUnitProtocol.swift + - PrebidMobile/CacheManagement/* + - PrebidMobile/ConfigurationAndTargeting/AgeUtils.swift + - PrebidMobile/ConfigurationAndTargeting/ClickbrowserType.swift + - PrebidMobile/ConfigurationAndTargeting/PrebidGAMVersionChecker.swift + - PrebidMobile/ConfigurationAndTargeting/PrebidSDKInitializer.swift + - PrebidMobile/ConfigurationAndTargeting/PrebidServerStatusRequester.swift + - PrebidMobile/ConfigurationAndTargeting/UserConsentDataManager.swift + - PrebidMobile/Constants.swift + - PrebidMobile/Dispatcher.swift + - PrebidMobile/ImageHelper.swift + - PrebidMobile/JSONConvertible.swift + - PrebidMobile/JsonDecodable.swift + - PrebidMobile/Logging/* + - PrebidMobile/StorageUtils.swift + - PrebidMobile/Tracker* + - PrebidMobile/UIViewExtension.swift + - PrebidMobile/Utils/* + - PrebidMobile/PrebidMobileRendering/AdTypes/AdView/AdConfiguration.swift + - PrebidMobile/PrebidMobileRendering/AdTypes/AdView/AdViewButtonDecorator.swift + - PrebidMobile/PrebidMobileRendering/AdTypes/AdView/HiddenWebViewManager.swift + - PrebidMobile/PrebidMobileRendering/Assets/PrebidImagesRepository.swift + - PrebidMobile/PrebidMobileRendering/AutoRefreshCountConfig.swift + - PrebidMobile/PrebidMobileRendering/Impression* + - PrebidMobile/PrebidMobileRendering/Networking* + - PrebidMobile/PrebidMobileRendering/Prebid/Integrations/GAM/AdLoading/AdLoadFlowControllerDelegate.swift + - PrebidMobile/PrebidMobileRendering/Prebid/Integrations/GAM/AdLoading/BannerAdLoaderDelegate.swift + - PrebidMobile/PrebidMobileRendering/Prebid/Integrations/GAM/BannerEventInteractionDelegate.swift + - PrebidMobile/PrebidMobileRendering/Prebid/Integrations/GAM/BannerEventLoadingDelegate.swift + - PrebidMobile/PrebidMobileRendering/Prebid/Integrations/GAM/InterstitialEventInteractionDelegate.swift + - PrebidMobile/PrebidMobileRendering/Prebid/Integrations/GAM/InterstitialEventLoadingDelegate.swift + - PrebidMobile/PrebidMobileRendering/Prebid/Integrations/GAM/RewardedEventInteractionDelegate.swift + - PrebidMobile/PrebidMobileRendering/Prebid/Integrations/GAM/RewardedEventLoadingDelegate.swift + - PrebidMobile/PrebidMobileRendering/Prebid/Integrations/GAM/BaseInterstitialAdUnitProtocol.swift + - PrebidMobile/PrebidMobileRendering/Prebid/Integrations/GAM/InterstitialEventHandlerProtocol.swift + - PrebidMobile/PrebidMobileRendering/Prebid/Integrations/MediationAPI/MediationUtils.swift + - PrebidMobile/PrebidMobileRendering/Prebid/Integrations/MediationAPI/MediationNativeUtils.swift + - PrebidMobile/PrebidMobileRendering/Prebid/Integrations/MediationAPI/MediationConstants.swift + - PrebidMobile/PrebidMobileRendering/Prebid/Integrations/MediationAPI/MediationBidInfoWrapper.swift + - PrebidMobile/PrebidMobileRendering/Prebid/Integrations/PBMStandaloneSDK/DemandResponseInfo.swift + - PrebidMobile/PrebidMobileRendering/Prebid/Integrations/PBMStandaloneSDK/EventHandlers/* + - PrebidMobile/PrebidMobileRendering/Prebid/PBMCore/* + - PrebidMobile/PrebidMobileRendering/Prebid/PBMCacheRenderers/* + - PrebidMobile/PrebidMobileRendering/PrebidServerEventTracker.swift + - PrebidMobile/PrebidMobileRendering/ServerEvent.swift + - PrebidMobile/PrebidMobileRendering/ServerSideConfiguration/* + - PrebidMobile/PrebidMobileRendering/Skadn* + - PrebidMobile/PrebidMobileRendering/Utilities/* +theme: apple diff --git a/EventHandlers/PrebidMobileAdMobAdapters/Sources/PrebidAdMobMediationBaseAdapter.swift b/EventHandlers/PrebidMobileAdMobAdapters/Sources/PrebidAdMobMediationBaseAdapter.swift index 96e3868a8..f58f7f9de 100644 --- a/EventHandlers/PrebidMobileAdMobAdapters/Sources/PrebidAdMobMediationBaseAdapter.swift +++ b/EventHandlers/PrebidMobileAdMobAdapters/Sources/PrebidAdMobMediationBaseAdapter.swift @@ -41,7 +41,7 @@ public class PrebidAdMobMediationBaseAdapter: NSObject, GADMediationAdapter { // Added for tests static func latestTestedGMAVersion() -> GADVersionNumber { - return GADVersionNumber(majorVersion: 11, minorVersion: 8, patchVersion: 0) + return GADVersionNumber(majorVersion: 11, minorVersion: 10, patchVersion: 0) } required public override init() { diff --git a/EventHandlers/PrebidMobileGAMEventHandlers/Sources/GAMUtils.swift b/EventHandlers/PrebidMobileGAMEventHandlers/Sources/GAMUtils.swift index ee2fc7e2a..1b73d07e8 100644 --- a/EventHandlers/PrebidMobileGAMEventHandlers/Sources/GAMUtils.swift +++ b/EventHandlers/PrebidMobileGAMEventHandlers/Sources/GAMUtils.swift @@ -59,7 +59,7 @@ public class GAMUtils: NSObject { // Added for tests static func latestTestedGMAVersion() -> GADVersionNumber { - return GADVersionNumber(majorVersion: 11, minorVersion: 8, patchVersion: 0) + return GADVersionNumber(majorVersion: 11, minorVersion: 10, patchVersion: 0) } // MARK: Private Methods diff --git a/EventHandlers/PrebidMobileMAXAdapters/Sources/PrebidMAXMediationAdapter.swift b/EventHandlers/PrebidMobileMAXAdapters/Sources/PrebidMAXMediationAdapter.swift index 46114a86f..f98d35f78 100644 --- a/EventHandlers/PrebidMobileMAXAdapters/Sources/PrebidMAXMediationAdapter.swift +++ b/EventHandlers/PrebidMobileMAXAdapters/Sources/PrebidMAXMediationAdapter.swift @@ -45,7 +45,6 @@ public class PrebidMAXMediationAdapter: ALMediationAdapter { // TODO: Add Prebid SDK initialization logic completionHandler(.initializedUnknown, nil) - Targeting.shared.subjectToCOPPA = ALPrivacySettings.isAgeRestrictedUser() } public override var sdkVersion: String { diff --git a/InternalTestApp/PrebidMobileDemoRendering/ViewControllers/Adapters/Prebid/AdMob/PrebidAdMobBannerViewController.swift b/InternalTestApp/PrebidMobileDemoRendering/ViewControllers/Adapters/Prebid/AdMob/PrebidAdMobBannerViewController.swift index 400035961..a578149ff 100644 --- a/InternalTestApp/PrebidMobileDemoRendering/ViewControllers/Adapters/Prebid/AdMob/PrebidAdMobBannerViewController.swift +++ b/InternalTestApp/PrebidMobileDemoRendering/ViewControllers/Adapters/Prebid/AdMob/PrebidAdMobBannerViewController.swift @@ -113,7 +113,7 @@ class PrebidAdMobBannerViewController: // imp[].ext.data if let adUnitContext = AppConfiguration.shared.adUnitContext { for dataPair in adUnitContext { - adUnit?.addContextData(dataPair.value, forKey: dataPair.key) + adUnit?.addContextData(key: dataPair.value, value: dataPair.key) } } diff --git a/InternalTestApp/PrebidMobileDemoRendering/ViewControllers/Adapters/Prebid/AdMob/PrebidAdMobInterstitialViewController.swift b/InternalTestApp/PrebidMobileDemoRendering/ViewControllers/Adapters/Prebid/AdMob/PrebidAdMobInterstitialViewController.swift index 150e08d0b..b89f154b2 100644 --- a/InternalTestApp/PrebidMobileDemoRendering/ViewControllers/Adapters/Prebid/AdMob/PrebidAdMobInterstitialViewController.swift +++ b/InternalTestApp/PrebidMobileDemoRendering/ViewControllers/Adapters/Prebid/AdMob/PrebidAdMobInterstitialViewController.swift @@ -109,7 +109,7 @@ class PrebidAdMobInterstitialViewController: NSObject, AdaptedController, Prebid // imp[].ext.data if let adUnitContext = AppConfiguration.shared.adUnitContext { for dataPair in adUnitContext { - adUnit?.addContextData(dataPair.value, forKey: dataPair.key) + adUnit?.addContextData(key: dataPair.value, value: dataPair.key) } } diff --git a/InternalTestApp/PrebidMobileDemoRendering/ViewControllers/Adapters/Prebid/AdMob/PrebidAdMobNativeViewController.swift b/InternalTestApp/PrebidMobileDemoRendering/ViewControllers/Adapters/Prebid/AdMob/PrebidAdMobNativeViewController.swift index 28a513e4b..86246f1b7 100644 --- a/InternalTestApp/PrebidMobileDemoRendering/ViewControllers/Adapters/Prebid/AdMob/PrebidAdMobNativeViewController.swift +++ b/InternalTestApp/PrebidMobileDemoRendering/ViewControllers/Adapters/Prebid/AdMob/PrebidAdMobNativeViewController.swift @@ -62,7 +62,7 @@ class PrebidAdMobNativeViewController: NSObject, AdaptedController, GADNativeAdL // imp[].ext.data if let adUnitContext = AppConfiguration.shared.adUnitContext { for dataPair in adUnitContext { - nativeAdUnit?.addContextData(dataPair.value, forKey: dataPair.key) + nativeAdUnit?.addContextData(key: dataPair.value, value: dataPair.key) } } diff --git a/InternalTestApp/PrebidMobileDemoRendering/ViewControllers/Adapters/Prebid/AdMob/PrebidAdMobRewardedViewController.swift b/InternalTestApp/PrebidMobileDemoRendering/ViewControllers/Adapters/Prebid/AdMob/PrebidAdMobRewardedViewController.swift index 0b8014911..df21373db 100644 --- a/InternalTestApp/PrebidMobileDemoRendering/ViewControllers/Adapters/Prebid/AdMob/PrebidAdMobRewardedViewController.swift +++ b/InternalTestApp/PrebidMobileDemoRendering/ViewControllers/Adapters/Prebid/AdMob/PrebidAdMobRewardedViewController.swift @@ -62,7 +62,7 @@ class PrebidAdMobRewardedViewController: NSObject, AdaptedController, PrebidConf // imp[].ext.data if let adUnitContext = AppConfiguration.shared.adUnitContext { for dataPair in adUnitContext { - adUnit?.addContextData(dataPair.value, forKey: dataPair.key) + adUnit?.addContextData(key: dataPair.value, value: dataPair.key) } } diff --git a/InternalTestApp/PrebidMobileDemoRendering/ViewControllers/Adapters/Prebid/MAX/PrebidMAXBannerController.swift b/InternalTestApp/PrebidMobileDemoRendering/ViewControllers/Adapters/Prebid/MAX/PrebidMAXBannerController.swift index c6769ef48..fdaf5c757 100644 --- a/InternalTestApp/PrebidMobileDemoRendering/ViewControllers/Adapters/Prebid/MAX/PrebidMAXBannerController.swift +++ b/InternalTestApp/PrebidMobileDemoRendering/ViewControllers/Adapters/Prebid/MAX/PrebidMAXBannerController.swift @@ -98,7 +98,7 @@ class PrebidMAXBannerController: NSObject, AdaptedController, PrebidConfigurable // imp[].ext.data if let adUnitContext = AppConfiguration.shared.adUnitContext { for dataPair in adUnitContext { - adUnit?.addContextData(dataPair.value, forKey: dataPair.key) + adUnit?.addContextData(key: dataPair.value, value: dataPair.key) } } diff --git a/InternalTestApp/PrebidMobileDemoRendering/ViewControllers/Adapters/Prebid/MAX/PrebidMAXInterstitialController.swift b/InternalTestApp/PrebidMobileDemoRendering/ViewControllers/Adapters/Prebid/MAX/PrebidMAXInterstitialController.swift index 218c44c2f..36da03bce 100644 --- a/InternalTestApp/PrebidMobileDemoRendering/ViewControllers/Adapters/Prebid/MAX/PrebidMAXInterstitialController.swift +++ b/InternalTestApp/PrebidMobileDemoRendering/ViewControllers/Adapters/Prebid/MAX/PrebidMAXInterstitialController.swift @@ -114,7 +114,7 @@ class PrebidMAXInterstitialController: NSObject, AdaptedController, PrebidConfig // imp[].ext.data if let adUnitContext = AppConfiguration.shared.adUnitContext { for dataPair in adUnitContext { - adUnit?.addContextData(dataPair.value, forKey: dataPair.key) + adUnit?.addContextData(key: dataPair.value, value: dataPair.key) } } diff --git a/InternalTestApp/PrebidMobileDemoRendering/ViewControllers/Adapters/Prebid/MAX/PrebidMAXNativeController.swift b/InternalTestApp/PrebidMobileDemoRendering/ViewControllers/Adapters/Prebid/MAX/PrebidMAXNativeController.swift index c312e26bf..9e44c4de5 100644 --- a/InternalTestApp/PrebidMobileDemoRendering/ViewControllers/Adapters/Prebid/MAX/PrebidMAXNativeController.swift +++ b/InternalTestApp/PrebidMobileDemoRendering/ViewControllers/Adapters/Prebid/MAX/PrebidMAXNativeController.swift @@ -68,7 +68,7 @@ class PrebidMAXNativeController: NSObject, AdaptedController { // imp[].ext.data if let adUnitContext = AppConfiguration.shared.adUnitContext { for dataPair in adUnitContext { - nativeAdUnit?.addContextData(dataPair.value, forKey: dataPair.key) + nativeAdUnit?.addContextData(key: dataPair.value, value: dataPair.key) } } diff --git a/InternalTestApp/PrebidMobileDemoRendering/ViewControllers/Adapters/Prebid/MAX/PrebidMAXRewardedController.swift b/InternalTestApp/PrebidMobileDemoRendering/ViewControllers/Adapters/Prebid/MAX/PrebidMAXRewardedController.swift index 0000ce79e..ca823c1f8 100644 --- a/InternalTestApp/PrebidMobileDemoRendering/ViewControllers/Adapters/Prebid/MAX/PrebidMAXRewardedController.swift +++ b/InternalTestApp/PrebidMobileDemoRendering/ViewControllers/Adapters/Prebid/MAX/PrebidMAXRewardedController.swift @@ -69,7 +69,7 @@ class PrebidMAXRewardedController: NSObject, AdaptedController, PrebidConfigurab // imp[].ext.data if let adUnitContext = AppConfiguration.shared.adUnitContext { for dataPair in adUnitContext { - adUnit?.addContextData(dataPair.value, forKey: dataPair.key) + adUnit?.addContextData(key: dataPair.value, value: dataPair.key) } } diff --git a/Podfile.lock b/Podfile.lock index d741af6eb..f9efac40e 100644 --- a/Podfile.lock +++ b/Podfile.lock @@ -1,11 +1,11 @@ PODS: - Alamofire (4.9.1) - - AppLovinSDK (12.6.1) + - AppLovinSDK (13.0.0) - Eureka (5.5.0) - - Google-Mobile-Ads-SDK (11.8.0): + - Google-Mobile-Ads-SDK (11.10.0): - GoogleUserMessagingPlatform (>= 1.1) - GoogleAds-IMA-iOS-SDK (3.23.0) - - GoogleUserMessagingPlatform (2.5.0) + - GoogleUserMessagingPlatform (2.6.0) - RxSwift (6.7.1) - SVProgressHUD (2.3.1): - SVProgressHUD/Core (= 2.3.1) @@ -33,11 +33,11 @@ SPEC REPOS: SPEC CHECKSUMS: Alamofire: 85e8a02c69d6020a0d734f6054870d7ecb75cf18 - AppLovinSDK: a892bbeff744749a8121bd863aa1399f7eef6ef1 + AppLovinSDK: c0ecb434df24008b6ecdd7f1e5b8587bc45ff381 Eureka: 1c18c7fcd8f772cc2ca42d6be36292dffa77eecb - Google-Mobile-Ads-SDK: c1c53687b572122c5b0bdaf354335bbf40fd81ef + Google-Mobile-Ads-SDK: 13e6e98edfd78ad8d8a791edb927658cc260a56f GoogleAds-IMA-iOS-SDK: ee2a68ed7a1a17c7bb81bdb1b81590b35a3fc8f3 - GoogleUserMessagingPlatform: 6b4f48a370e77ce121d034c908cc6ee4fdafaf13 + GoogleUserMessagingPlatform: 0c3a08353e53ce8c2feab7addd0b652cde522450 RxSwift: b9a93a26031785159e11abd40d1a55bcb8057e52 SVProgressHUD: 4837c74bdfe2e51e8821c397825996a8d7de6e22 diff --git a/PrebidMobile.xcodeproj/project.pbxproj b/PrebidMobile.xcodeproj/project.pbxproj index fa064f43b..7e5fcc3e5 100644 --- a/PrebidMobile.xcodeproj/project.pbxproj +++ b/PrebidMobile.xcodeproj/project.pbxproj @@ -106,6 +106,7 @@ 53A657B12A8B650900AE0B4F /* PBMORTBSDKConfiguration.h in Headers */ = {isa = PBXBuildFile; fileRef = 53A657AE2A8B64B300AE0B4F /* PBMORTBSDKConfiguration.h */; settings = {ATTRIBUTES = (Public, ); }; }; 53A657B52A8B8B0500AE0B4F /* PBMORTBBidResponseExtPrebid.h in Headers */ = {isa = PBXBuildFile; fileRef = 53A657B42A8B8B0500AE0B4F /* PBMORTBBidResponseExtPrebid.h */; settings = {ATTRIBUTES = (Public, ); }; }; 53A657B72A8B8B6400AE0B4F /* PBMORTBBidResponseExtPrebid.m in Sources */ = {isa = PBXBuildFile; fileRef = 53A657B62A8B8B6400AE0B4F /* PBMORTBBidResponseExtPrebid.m */; }; + 53A8CBDB2C64D12A008ABEA7 /* SingleContainerInt.swift in Sources */ = {isa = PBXBuildFile; fileRef = 53A8CBDA2C64D12A008ABEA7 /* SingleContainerInt.swift */; }; 53B221CF2A0E3D2800C91CCB /* PrebidJSLibrary.swift in Sources */ = {isa = PBXBuildFile; fileRef = 53B221CE2A0E3D2800C91CCB /* PrebidJSLibrary.swift */; }; 53B221D12A0E3D3D00C91CCB /* PrebidJSLibraryManager.swift in Sources */ = {isa = PBXBuildFile; fileRef = 53B221D02A0E3D3D00C91CCB /* PrebidJSLibraryManager.swift */; }; 53B221D32A0E3DA900C91CCB /* PrebidJSLibraryManagerTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 53B221D22A0E3DA900C91CCB /* PrebidJSLibraryManagerTests.swift */; }; @@ -967,6 +968,7 @@ 53A657AF2A8B64C200AE0B4F /* PBMORTBSDKConfiguration.m */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.objc; path = PBMORTBSDKConfiguration.m; sourceTree = ""; }; 53A657B42A8B8B0500AE0B4F /* PBMORTBBidResponseExtPrebid.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = PBMORTBBidResponseExtPrebid.h; sourceTree = ""; }; 53A657B62A8B8B6400AE0B4F /* PBMORTBBidResponseExtPrebid.m */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.objc; path = PBMORTBBidResponseExtPrebid.m; sourceTree = ""; }; + 53A8CBDA2C64D12A008ABEA7 /* SingleContainerInt.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = SingleContainerInt.swift; sourceTree = ""; }; 53B221CE2A0E3D2800C91CCB /* PrebidJSLibrary.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = PrebidJSLibrary.swift; sourceTree = ""; }; 53B221D02A0E3D3D00C91CCB /* PrebidJSLibraryManager.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = PrebidJSLibraryManager.swift; sourceTree = ""; }; 53B221D22A0E3DA900C91CCB /* PrebidJSLibraryManagerTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = PrebidJSLibraryManagerTests.swift; sourceTree = ""; }; @@ -1909,6 +1911,7 @@ 53E45A0227FCD09C0095C0B2 /* BannerParameters.swift */, 53E3910D27FCD60800DBA2F7 /* VideoParameters.swift */, 53A368EA2AB2E95E00A03B3E /* NativeParameters.swift */, + 53A8CBDA2C64D12A008ABEA7 /* SingleContainerInt.swift */, ); path = Parameters; sourceTree = ""; @@ -4194,6 +4197,7 @@ 5BC3792B271F1D0000444D5E /* PBMConstants.m in Sources */, 5BC37A61271F1D0000444D5E /* PBMORTBBidExt.m in Sources */, FAEE4D13262DC2B200AD9966 /* AdUnit.swift in Sources */, + 53A8CBDB2C64D12A008ABEA7 /* SingleContainerInt.swift in Sources */, 5BC379CF271F1D0000444D5E /* PBMAdLoadManagerBase.m in Sources */, 924F661C27FDBA5200C8DAF7 /* PBMORTBAdConfiguration.m in Sources */, 5BC379FB271F1D0000444D5E /* PBMExternalURLOpenCallbacks.m in Sources */, @@ -4531,6 +4535,8 @@ MARKETING_VERSION = 2.3.0; MODULEMAP_FILE = PrebidMobile/BuildFiles/PrebidMobile.modulemap; SKIP_INSTALL = YES; + SUPPORTED_PLATFORMS = "iphoneos iphonesimulator"; + SUPPORTS_MACCATALYST = NO; SWIFT_OPTIMIZATION_LEVEL = "-Onone"; SWIFT_VERSION = 5.0; TARGETED_DEVICE_FAMILY = "1,2"; @@ -4567,6 +4573,8 @@ MARKETING_VERSION = 2.3.0; MODULEMAP_FILE = PrebidMobile/BuildFiles/PrebidMobile.modulemap; SKIP_INSTALL = YES; + SUPPORTED_PLATFORMS = "iphoneos iphonesimulator"; + SUPPORTS_MACCATALYST = NO; SWIFT_VERSION = 5.0; TARGETED_DEVICE_FAMILY = "1,2"; }; diff --git a/PrebidMobile/AdUnits/AdUnit.swift b/PrebidMobile/AdUnits/AdUnit.swift index 9d1358942..15c29e380 100644 --- a/PrebidMobile/AdUnits/AdUnit.swift +++ b/PrebidMobile/AdUnits/AdUnit.swift @@ -13,9 +13,11 @@ import UIKit import ObjectiveC.runtime +/// Base class for ad units built for original type of integration. @objcMembers public class AdUnit: NSObject, DispatcherDelegate { + /// ORTB: imp[].ext.data.adslot public var pbAdSlot: String? { get { adUnitConfig.getPbAdSlot()} set { adUnitConfig.setPbAdSlot(newValue) } @@ -33,18 +35,25 @@ public class AdUnit: NSObject, DispatcherDelegate { private var bidRequester: PBMBidRequesterProtocol - //This flag is set to check if the refresh needs to be made though the user has not invoked the fetch demand after initialization + /// This flag is set to check if the refresh needs to be made though the user has not invoked the fetch demand after initialization private var isInitialFetchDemandCallMade = false private var adServerObject: AnyObject? private var lastFetchDemandCompletion: ((_ bidInfo: BidInfo) -> Void)? - //notification flag set to check if the prebid response is received within the specified time + /// notification flag set to check if the prebid response is received within the specified time private var didReceiveResponse = false - //notification flag set to determine if delegate call needs to be made after timeout delegate is sent + /// notification flag set to determine if delegate call needs to be made after timeout delegate is sent private var timeOutSignalSent = false + + /// Initializes a new `AdUnit` instance with the specified configuration ID, size, and ad formats. + /// + /// - Parameters: + /// - configId: The configuration ID for the ad unit. + /// - size: The primary size of the ad. If `nil`, a default size of `.zero` is used. + /// - adFormats: A set of ad formats supported by the ad unit. public init(configId: String, size: CGSize?, adFormats: Set) { adUnitConfig = AdUnitConfig(configId: configId, size: size ?? CGSize.zero) adUnitConfig.adConfiguration.isOriginalAPI = true @@ -70,6 +79,12 @@ public class AdUnit: NSObject, DispatcherDelegate { } //TODO: dynamic is used by tests + + /// Makes bid request and provides the result as a dictionary of key-value pairs. + /// + /// - Parameter completion: A closure called with the result code and an optional dictionary of targeting keywords. + /// - result: The result code indicating the outcome of the demand fetch. + /// - kvResultDict: A dictionary containing key-value pairs, or `nil` if no demand was fetched. @available(*, deprecated, message: "Deprecated. Use fetchDemand(completion: @escaping (_ bidInfo: BidInfo) -> Void) instead.") dynamic public func fetchDemand(completion: @escaping(_ result: ResultCode, _ kvResultDict: [String : String]?) -> Void) { let dictContainer = DictionaryContainer() @@ -83,10 +98,18 @@ public class AdUnit: NSObject, DispatcherDelegate { } } + /// Makes bid request and provides the result as a `BidInfo` object. + /// + /// - Parameter completionBidInfo: A closure called with a `BidInfo` object representing the fetched demand. dynamic public func fetchDemand(completionBidInfo: @escaping (_ bidInfo: BidInfo) -> Void) { baseFetchDemand(completion: completionBidInfo) } + /// Makes bid request for a specific ad object and provides the result code. Setups targeting keywords into the adObject. + /// + /// - Parameters: + /// - adObject: The ad object for which demand is being fetched. + /// - completion: A closure called with the result code indicating the outcome of the demand fetch. dynamic public func fetchDemand(adObject: AnyObject, completion: @escaping(_ result: ResultCode) -> Void) { baseFetchDemand(adObject: adObject) { bidInfo in DispatchQueue.main.async { @@ -193,35 +216,28 @@ public class AdUnit: NSObject, DispatcherDelegate { // MARK: - adunit ext data aka inventory data (imp[].ext.data) - /** - * This method obtains the context data keyword & value for adunit context targeting - * if the key already exists the value will be appended to the list. No duplicates will be added - */ + + /// This method obtains the context data keyword & value for adunit context targeting + /// If the key already exists the value will be appended to the list. No duplicates will be added @available(*, deprecated, message: "This method is deprecated. Please, use addExtData method instead.") public func addContextData(key: String, value: String) { addExtData(key: key, value: value) } - - /** - * This method obtains the context data keyword & values for adunit context targeting - * the values if the key already exist will be replaced with the new set of values - */ + + /// This method obtains the context data keyword & values for adunit context targeting + /// The values if the key already exist will be replaced with the new set of values @available(*, deprecated, message: "This method is deprecated. Please, use updateExtData method instead.") public func updateContextData(key: String, value: Set) { updateExtData(key: key, value: value) } - /** - * This method allows to remove specific context data keyword & values set from adunit context targeting - */ + /// This method allows to remove specific context data keyword & values set from adunit context targeting @available(*, deprecated, message: "This method is deprecated. Please, use removeExtData method instead.") public func removeContextData(forKey: String) { removeExtData(forKey: forKey) } - /** - * This method allows to remove all context data set from adunit context targeting - */ + /// This method allows to remove all context data set from adunit context targeting @available(*, deprecated, message: "This method is deprecated. Please, use clearExtData method instead.") public func clearContextData() { clearExtData() @@ -232,98 +248,74 @@ public class AdUnit: NSObject, DispatcherDelegate { return adUnitConfig.getExtData() } - /** - * This method obtains the ext data keyword & value for adunit targeting - * if the key already exists the value will be appended to the list. No duplicates will be added - */ + /// This method obtains the ext data keyword & value for adunit targeting. + /// If the key already exists the value will be appended to the list. No duplicates will be added public func addExtData(key: String, value: String) { adUnitConfig.addExtData(key: key, value: value) } - /** - * This method obtains the ext data keyword & values for adunit targeting - * the values if the key already exist will be replaced with the new set of values - */ + /// This method obtains the ext data keyword & values for adunit targeting + /// The values if the key already exist will be replaced with the new set of values public func updateExtData(key: String, value: Set) { adUnitConfig.updateExtData(key: key, value: value) } - /** - * This method allows to remove specific ext data keyword & values set from adunit targeting - */ + /// This method allows to remove specific ext data keyword & values set from adunit targeting public func removeExtData(forKey: String) { adUnitConfig.removeExtData(for: forKey) } - /** - * This method allows to remove all ext data set from adunit targeting - */ + /// This method allows to remove all ext data set from adunit targeting public func clearExtData() { adUnitConfig.clearExtData() } // MARK: - adunit ext keywords (imp[].ext.keywords) - /** - * This method obtains the context keyword for adunit context targeting - * Inserts the given element in the set if it is not already present. - */ + /// This method obtains the context keyword for adunit context targeting + /// Inserts the given element in the set if it is not already present. @available(*, deprecated, message: "This method is deprecated. Please, use addExtKeyword method instead.") public func addContextKeyword(_ newElement: String) { addExtKeyword(newElement) } - /** - * This method obtains the context keyword set for adunit context targeting - * Adds the elements of the given set to the set. - */ + /// This method obtains the context keyword set for adunit context targeting + /// Adds the elements of the given set to the set. @available(*, deprecated, message: "This method is deprecated. Please, use addExtKeywords method instead.") public func addContextKeywords(_ newElements: Set) { addExtKeywords(newElements) } - /** - * This method allows to remove specific context keyword from adunit context targeting - */ + /// This method allows to remove specific context keyword from adunit context targeting @available(*, deprecated, message: "This method is deprecated. Please, use removeExtKeyword method instead.") public func removeContextKeyword(_ element: String) { removeExtKeyword(element) } - /** - * This method allows to remove all keywords from the set of adunit context targeting - */ + /// This method allows to remove all keywords from the set of adunit context targeting @available(*, deprecated, message: "This method is deprecated. Please, use clearExtKeywords method instead.") public func clearContextKeywords() { clearExtKeywords() } - - /** - * This method obtains the keyword for adunit targeting - * Inserts the given element in the set if it is not already present. - */ + + /// This method obtains the keyword for adunit targeting + /// Inserts the given element in the set if it is not already present. public func addExtKeyword(_ newElement: String) { adUnitConfig.addExtKeyword(newElement) } - /** - * This method obtains the keyword set for adunit targeting - * Adds the elements of the given set to the set. - */ + /// This method obtains the keyword set for adunit targeting + /// Adds the elements of the given set to the set. public func addExtKeywords(_ newElements: Set) { adUnitConfig.addExtKeywords(newElements) } - /** - * This method allows to remove specific keyword from adunit targeting - */ + /// This method allows to remove specific keyword from adunit targeting public func removeExtKeyword(_ element: String) { adUnitConfig.removeExtKeyword(element) } - /** - * This method allows to remove all keywords from the set of adunit targeting - */ + /// This method allows to remove all keywords from the set of adunit targeting public func clearExtKeywords() { adUnitConfig.clearExtKeywords() } @@ -335,75 +327,109 @@ public class AdUnit: NSObject, DispatcherDelegate { // MARK: - App Content (app.content.data) + /// Sets the app content object, replacing any existing content. + /// + /// - Parameter appContentObject: The `PBMORTBAppContent` object representing the app's content. public func setAppContent(_ appContentObject: PBMORTBAppContent) { adUnitConfig.setAppContent(appContentObject) } + /// Retrieves the current app content object. + /// + /// - Returns: The current `PBMORTBAppContent` object, or `nil` if no content is set. public func getAppContent() -> PBMORTBAppContent? { return adUnitConfig.getAppContent() } + /// Clears the current app content object. public func clearAppContent() { adUnitConfig.clearAppContent() } + /// Adds an array of content data objects to the app content. + /// + /// - Parameter dataObjects: An array of `PBMORTBContentData` objects to add. public func addAppContentData(_ dataObjects: [PBMORTBContentData]) { adUnitConfig.addAppContentData(dataObjects) } + /// Removes a specific content data object from the app content. + /// + /// - Parameter dataObject: The `PBMORTBContentData` object to remove. public func removeAppContentData(_ dataObject: PBMORTBContentData) { adUnitConfig.removeAppContentData(dataObject) } + /// Clears all content data objects from the app content. public func clearAppContentData() { adUnitConfig.clearAppContentData() } // MARK: - User Data (user.data) + /// Retrieves the current user data. + /// + /// - Returns: An array of `PBMORTBContentData` objects representing the user data, or `nil` if no data is available. public func getUserData() -> [PBMORTBContentData]? { return adUnitConfig.getUserData() } + /// Adds an array of user data objects. + /// + /// - Parameter userDataObjects: An array of `PBMORTBContentData` objects to add to the user data. public func addUserData(_ userDataObjects: [PBMORTBContentData]) { adUnitConfig.addUserData(userDataObjects) } + /// Removes a specific user data object. + /// + /// - Parameter userDataObject: The `PBMORTBContentData` object to remove from the user data. public func removeUserData(_ userDataObject: PBMORTBContentData) { adUnitConfig.removeUserData(userDataObject) } + /// Clears all user data. public func clearUserData() { adUnitConfig.clearUserData() } // MARK: GPID + /// Sets the GPID for the ad unit. + /// + /// - Parameter gpid: The GPID string to set. Can be `nil` to clear the GPID. public func setGPID(_ gpid: String?) { adUnitConfig.gpid = gpid } + /// Retrieves the current GPID for the ad unit. + /// + /// - Returns: The GPID string, or `nil` if no GPID is set. public func getGPID() -> String? { return adUnitConfig.gpid } // MARK: Global ORTBObject + /// Sets the OpenRTB configuration string for the ad unit. + /// + /// - Parameter ortbObject: The OpenRTB configuration string to set. Can be `nil` to clear the configuration. public func setOrtbConfig(_ ortbObject: String?) { adUnitConfig.ortbConfig = ortbObject } + /// Retrieves the current OpenRTB configuration string for the ad unit. + /// + /// - Returns: The OpenRTB configuration string, or `nil` if no configuration is set. public func getOrtbConfig() -> String? { return adUnitConfig.ortbConfig } // MARK: - others - /** - * This method allows to set the auto refresh period for the demand - * - * - Parameter time: refresh time interval - */ + + /// This method allows to set the auto refresh period for the demand + /// - Parameter time: refresh time interval public func setAutoRefreshMillis(time: Double) { guard checkRefreshTime(time) else { @@ -425,13 +451,12 @@ public class AdUnit: NSObject, DispatcherDelegate { } } - /** - * This method stops the auto refresh of demand - */ + /// This method stops the auto refresh of demand public func stopAutoRefresh() { stopDispatcher() } + /// This method resumes the auto refresh of demand public func resumeAutoRefresh() { if dispatcher?.state == .stopped { if isInitialFetchDemandCallMade { diff --git a/PrebidMobile/AdUnits/BannerAdUnit.swift b/PrebidMobile/AdUnits/BannerAdUnit.swift index 2f9e4742a..2a6128ef7 100644 --- a/PrebidMobile/AdUnits/BannerAdUnit.swift +++ b/PrebidMobile/AdUnits/BannerAdUnit.swift @@ -15,33 +15,44 @@ import UIKit +/// A class representing a banner ad unit for original type of integration. public class BannerAdUnit: AdUnit, BannerBasedAdUnitProtocol, VideoBasedAdUnitProtocol { + /// A deprecated property for banner ad parameters. @available(*, deprecated, message: "This property is deprecated. Please, use bannerParameters instead.") public var parameters: BannerParameters { get { adUnitConfig.adConfiguration.bannerParameters } set { adUnitConfig.adConfiguration.bannerParameters = newValue } } + /// The banner ad parameters used to configure the ad unit. public var bannerParameters: BannerParameters { get { adUnitConfig.adConfiguration.bannerParameters } set { adUnitConfig.adConfiguration.bannerParameters = newValue } } + /// The video ad parameters used to configure the ad unit. public var videoParameters: VideoParameters { get { adUnitConfig.adConfiguration.videoParameters } set { adUnitConfig.adConfiguration.videoParameters = newValue } } + /// The set of ad formats for the ad unit. public var adFormats: Set { get { adUnitConfig.adFormats } set { adUnitConfig.adFormats = newValue } } + /// Initializes a new `BannerAdUnit` with the specified configuration ID and size. + /// - Parameters: + /// - configId: The unique identifier for the ad unit configuration. + /// - size: The size of the banner ad unit. public init(configId: String, size: CGSize) { super.init(configId: configId, size: size, adFormats: [.banner]) } + /// Adds additional sizes to the banner ad unit's configuration. + /// - Parameter sizes: An array of `CGSize` objects representing additional sizes. public func addAdditionalSize(sizes: [CGSize]) { if super.adUnitConfig.additionalSizes == nil { super.adUnitConfig.additionalSizes = [CGSize]() diff --git a/PrebidMobile/AdUnits/InstreamVideoAdUnit.swift b/PrebidMobile/AdUnits/InstreamVideoAdUnit.swift index e01bcab6d..b38874946 100644 --- a/PrebidMobile/AdUnits/InstreamVideoAdUnit.swift +++ b/PrebidMobile/AdUnits/InstreamVideoAdUnit.swift @@ -15,13 +15,18 @@ import UIKit +/// Represents an instream video ad unit for original type of integration. public class InstreamVideoAdUnit: AdUnit, VideoBasedAdUnitProtocol { + /// The video parameters for this ad unit. public var videoParameters: VideoParameters { get { adUnitConfig.adConfiguration.videoParameters } set { adUnitConfig.adConfiguration.videoParameters = newValue } } - + + /// Initializes a new instream video ad unit. + /// - Parameter configId: The unique identifier for the ad unit configuration. + /// - Parameter size: The size of the ad. public init(configId: String, size: CGSize) { super.init(configId: configId, size: size, adFormats: [.video]) } diff --git a/PrebidMobile/AdUnits/InterstitialAdUnit.swift b/PrebidMobile/AdUnits/InterstitialAdUnit.swift index 4433ef49b..58b042ee0 100644 --- a/PrebidMobile/AdUnits/InterstitialAdUnit.swift +++ b/PrebidMobile/AdUnits/InterstitialAdUnit.swift @@ -15,29 +15,36 @@ import UIKit +/// Represents an interstitial ad unit built for original type of integration. public class InterstitialAdUnit: AdUnit, BannerBasedAdUnitProtocol, VideoBasedAdUnitProtocol { + /// The deprecated banner parameters for this ad unit. @available(*, deprecated, message: "This property is deprecated. Please, use bannerParameters instead.") public var parameters: BannerParameters { get { adUnitConfig.adConfiguration.bannerParameters } set { adUnitConfig.adConfiguration.bannerParameters = newValue } } + /// The banner parameters for this ad unit. public var bannerParameters: BannerParameters { get { adUnitConfig.adConfiguration.bannerParameters } set { adUnitConfig.adConfiguration.bannerParameters = newValue } } + /// The video parameters for this ad unit. public var videoParameters: VideoParameters { get { adUnitConfig.adConfiguration.videoParameters } set { adUnitConfig.adConfiguration.videoParameters = newValue } } + /// The ad formats for the ad unit. public var adFormats: Set { get { adUnitConfig.adFormats } set { adUnitConfig.adFormats = newValue } } + /// Initializes a new interstitial ad unit with a unique configuration identifier. + /// - Parameter configId: The unique identifier for the ad unit configuration. public init(configId: String) { super.init(configId: configId, size: nil, adFormats: [.banner]) @@ -46,6 +53,10 @@ public class InterstitialAdUnit: AdUnit, BannerBasedAdUnitProtocol, VideoBasedAd adUnitConfig.adConfiguration.videoParameters.placement = .Interstitial } + /// Initializes a new interstitial ad unit with a minimum width and height percentage. + /// - Parameter configId: The unique identifier for the ad unit configuration. + /// - Parameter minWidthPerc: The minimum width percentage of the ad. + /// - Parameter minHeightPerc: The minimum height percentage of the ad. public convenience init(configId: String, minWidthPerc: Int, minHeightPerc: Int) { self.init(configId: configId) diff --git a/PrebidMobile/AdUnits/MultiformatAdUnit/BidInfo.swift b/PrebidMobile/AdUnits/MultiformatAdUnit/BidInfo.swift index c58ca6bd9..c27b6a3ab 100644 --- a/PrebidMobile/AdUnits/MultiformatAdUnit/BidInfo.swift +++ b/PrebidMobile/AdUnits/MultiformatAdUnit/BidInfo.swift @@ -15,6 +15,7 @@ limitations under the License. import Foundation +/// Contains information about bid. @objcMembers @objc(PBMBidInfo) public class BidInfo: NSObject { @@ -25,13 +26,29 @@ public class BidInfo: NSObject { /// Key to get Prebid imp event from `events` public static let EVENT_IMP = "ext.prebid.events.imp" + /// The result code of the bid request public private(set) var resultCode: ResultCode + + /// Targeting keywords associated with the bid public private(set) var targetingKeywords: [String: String]? + + /// The expiration time of the bid public private(set) var exp: Double? + + /// The cache ID for native ads public private(set) var nativeAdCacheId: String? + + /// Events related to the bid public private(set) var events: [String: String] - public init(resultCode: ResultCode, targetingKeywords: [String : String]? = nil, exp: Double? = nil, + /// Initializes a new `BidInfo` instance with the specified parameters. + /// - Parameters: + /// - resultCode: The result code of the bid request. + /// - targetingKeywords: Optional targeting keywords associated with the bid. + /// - exp: Optional expiration time of the bid. + /// - nativeAdCacheId: Optional cache ID for native ads. + /// - events: Optional dictionary of events related to the bid. + public init(resultCode: ResultCode, targetingKeywords: [String : String]? = nil, exp: Double? = nil, nativeAdCacheId: String? = nil, events: [String: String] = [:]) { self.resultCode = resultCode self.targetingKeywords = targetingKeywords @@ -43,6 +60,7 @@ public class BidInfo: NSObject { } // Obj-C API + /// Retrieves the expiration time of the bid as an `NSNumber`. public func getExp() -> NSNumber? { if let exp { return NSNumber(value: exp) diff --git a/PrebidMobile/AdUnits/MultiformatAdUnit/PrebidAdUnit.swift b/PrebidMobile/AdUnits/MultiformatAdUnit/PrebidAdUnit.swift index 3098506f2..97c9c1b0b 100644 --- a/PrebidMobile/AdUnits/MultiformatAdUnit/PrebidAdUnit.swift +++ b/PrebidMobile/AdUnits/MultiformatAdUnit/PrebidAdUnit.swift @@ -15,9 +15,11 @@ import Foundation +/// Multiformat ad unit. Built for original API. @objcMembers public class PrebidAdUnit: NSObject { + /// The ad slot identifier for the Prebid ad unit. public var pbAdSlot: String? { get { adUnit.pbAdSlot } set { adUnit.pbAdSlot = newValue } @@ -25,11 +27,18 @@ public class PrebidAdUnit: NSObject { private let adUnit: AdUnit + /// Initializes a new `PrebidAdUnit` with the given configuration ID. + /// - Parameter configId: The configuration ID for the ad unit. public init(configId: String) { adUnit = AdUnit(configId: configId, size: CGSize.zero, adFormats: []) super.init() } + /// Makes bid request for the specified ad object and request config. Setups targeting keywords into the adObject. + /// - Parameters: + /// - adObject: The ad object to fetch demand for. + /// - request: The `PrebidRequest` containing the demand request parameters. + /// - completion: A closure to be called with the `BidInfo` result. public func fetchDemand(adObject: AnyObject, request: PrebidRequest, completion: @escaping (BidInfo) -> Void) { guard requestHasParameters(request) else { @@ -45,6 +54,10 @@ public class PrebidAdUnit: NSObject { } } + /// Makes bid request for the specified request config. + /// - Parameters: + /// - request: The `PrebidRequest` containing the demand request parameters. + /// - completion: A closure to be called with the `BidInfo` result. public func fetchDemand(request: PrebidRequest, completion: @escaping (BidInfo) -> Void) { guard requestHasParameters(request) else { completion(BidInfo(resultCode: .prebidInvalidRequest)) @@ -62,22 +75,20 @@ public class PrebidAdUnit: NSObject { // MARK: - Auto refresh API - /** - * This method allows to set the auto refresh period for the demand - * - * - Parameter time: refresh time interval - */ + + /// This method allows to set the auto refresh period for the demand + /// + /// - Parameter time: refresh time interval public func setAutoRefreshMillis(time: Double) { adUnit.setAutoRefreshMillis(time: time) } - /** - * This method stops the auto refresh of demand - */ + /// This method stops the auto refresh of demand public func stopAutoRefresh() { adUnit.stopAutoRefresh() } + /// This method resumes the auto refresh of demand public func resumeAutoRefresh() { adUnit.resumeAutoRefresh() } diff --git a/PrebidMobile/AdUnits/MultiformatAdUnit/PrebidRequest.swift b/PrebidMobile/AdUnits/MultiformatAdUnit/PrebidRequest.swift index ea1238b20..46794377b 100644 --- a/PrebidMobile/AdUnits/MultiformatAdUnit/PrebidRequest.swift +++ b/PrebidMobile/AdUnits/MultiformatAdUnit/PrebidRequest.swift @@ -15,6 +15,7 @@ import Foundation +/// Class that contains properties and methods to configure Prebid request. @objcMembers public class PrebidRequest: NSObject { @@ -37,6 +38,13 @@ public class PrebidRequest: NSObject { private var userData: [PBMORTBContentData]? private var extKeywords = Set() + /// Initializes a new `PrebidRequest` with the given parameters. + /// - Parameters: + /// - bannerParameters: The banner parameters for the ad request. + /// - videoParameters: The video parameters for the ad request. + /// - nativeParameters: The native parameters for the ad request. + /// - isInterstitial: Indicates if the request is for an interstitial ad. + /// - isRewarded: Indicates if the request is for a rewarded ad. public init(bannerParameters: BannerParameters? = nil, videoParameters: VideoParameters? = nil, nativeParameters: NativeParameters? = nil, isInterstitial: Bool = false, isRewarded: Bool = false) { self.bannerParameters = bannerParameters @@ -50,16 +58,17 @@ public class PrebidRequest: NSObject { // MARK: GPID + /// Sets the GPID for the ad request. + /// - Parameter gpid: The GPID to set. public func setGPID(_ gpid: String?) { self.gpid = gpid } // MARK: - adunit ext data aka inventory data (imp[].ext.data) - /** - * This method obtains the ext data keyword & value for adunit targeting - * if the key already exists the value will be appended to the list. No duplicates will be added - */ + + /// This method obtains the ext data keyword & value for adunit targeting + /// if the key already exists the value will be appended to the list. No duplicates will be added public func addExtData(key: String, value: String) { if extData[key] == nil { extData[key] = Set() @@ -68,24 +77,19 @@ public class PrebidRequest: NSObject { extData[key]?.insert(value) } - /** - * This method obtains the ext data keyword & values for adunit targeting - * the values if the key already exist will be replaced with the new set of values - */ + + /// This method obtains the ext data keyword & values for adunit targeting + /// the values if the key already exist will be replaced with the new set of values public func updateExtData(key: String, value: Set) { extData[key] = value } - /** - * This method allows to remove specific ext data keyword & values set from adunit targeting - */ + /// This method allows to remove specific ext data keyword & values set from adunit targeting public func removeExtData(forKey: String) { extData.removeValue(forKey: forKey) } - /** - * This method allows to remove all ext data set from adunit targeting - */ + /// This method allows to remove all ext data set from adunit targeting public func clearExtData() { extData.removeAll() } @@ -96,32 +100,24 @@ public class PrebidRequest: NSObject { // MARK: - adunit ext keywords (imp[].ext.keywords) - /** - * This method obtains the keyword for adunit targeting - * Inserts the given element in the set if it is not already present. - */ + /// This method obtains the keyword for adunit targeting + /// Inserts the given element in the set if it is not already present. public func addExtKeyword(_ newElement: String) { extKeywords.insert(newElement) } - /** - * This method obtains the keyword set for adunit targeting - * Adds the elements of the given set to the set. - */ + /// This method obtains the keyword set for adunit targeting + /// Adds the elements of the given set to the set. public func addExtKeywords(_ newElements: Set) { extKeywords.formUnion(newElements) } - /** - * This method allows to remove specific keyword from adunit targeting - */ + /// This method allows to remove specific keyword from adunit targeting public func removeExtKeyword(_ element: String) { extKeywords.remove(element) } - /** - * This method allows to remove all keywords from the set of adunit targeting - */ + /// This method allows to remove all keywords from the set of adunit targeting public func clearExtKeywords() { extKeywords.removeAll() } @@ -132,14 +128,19 @@ public class PrebidRequest: NSObject { // MARK: - App Content (app.content.data) + /// Sets the app content for the ad request. + /// - Parameter appContentObject: The `PBMORTBAppContent` to set. public func setAppContent(_ appContentObject: PBMORTBAppContent) { self.appContent = appContentObject } + /// Clears the app content for the ad request. public func clearAppContent() { appContent = nil } + /// Adds data to the app content. + /// - Parameter dataObjects: The array of `PBMORTBContentData` to add. public func addAppContentData(_ dataObjects: [PBMORTBContentData]) { if appContent == nil { appContent = PBMORTBAppContent() @@ -152,12 +153,15 @@ public class PrebidRequest: NSObject { appContent?.data?.append(contentsOf: dataObjects) } + /// Removes specific data from the app content. + /// - Parameter dataObject: The `PBMORTBContentData` to remove. public func removeAppContentData(_ dataObject: PBMORTBContentData) { if let appContentData = appContent?.data, appContentData.contains(dataObject) { appContent?.data?.removeAll(where: { $0 == dataObject }) } } + /// Clears all data from the app content. public func clearAppContentData() { appContent?.data?.removeAll() } @@ -168,6 +172,8 @@ public class PrebidRequest: NSObject { // MARK: - User Data (user.data) + /// Adds user data to the ad request. + /// - Parameter userDataObjects: The array of `PBMORTBContentData` to add. public func addUserData(_ userDataObjects: [PBMORTBContentData]) { if userData == nil { userData = [PBMORTBContentData]() @@ -176,12 +182,15 @@ public class PrebidRequest: NSObject { userData?.append(contentsOf: userDataObjects) } + /// Removes specific user data from the ad request. + /// - Parameter userDataObject: The `PBMORTBContentData` to remove. public func removeUserData(_ userDataObject: PBMORTBContentData) { if let userData = userData, userData.contains(userDataObject) { self.userData?.removeAll { $0 == userDataObject } } } + /// Clears all user data from the ad request. public func clearUserData() { userData?.removeAll() } diff --git a/PrebidMobile/AdUnits/Native/ContextSubType.swift b/PrebidMobile/AdUnits/Native/ContextSubType.swift index c09e27506..2ed1470d2 100644 --- a/PrebidMobile/AdUnits/Native/ContextSubType.swift +++ b/PrebidMobile/AdUnits/Native/ContextSubType.swift @@ -15,32 +15,47 @@ import Foundation +/// Native context subtype asset. @objcMembers public class ContextSubType: SingleContainerInt { + /// Represents a general context type. public static let General = ContextSubType(10) - + + + /// Represents an article context type. public static let Article = ContextSubType(11) - + + /// Represents a video context type. public static let Video = ContextSubType(12) - + + /// Represents an audio context type. public static let Audio = ContextSubType(13) - + + /// Represents an image context type. public static let Image = ContextSubType(14) - + + /// Represents a user-generated content context type. public static let UserGenerated = ContextSubType(15) - + + /// Represents a social media context type. public static let Social = ContextSubType(20) - + + /// Represents an email context type. public static let email = ContextSubType(21) - + + /// Represents a chat or instant messaging context type. public static let chatIM = ContextSubType(22) - + + /// Represents a product selling context type. public static let SellingProduct = ContextSubType(30) - + + /// Represents an App Store context type. public static let AppStore = ContextSubType(31) - + + /// Represents a review site context type. public static let ReviewSite = ContextSubType(32) - + + /// Represents a custom context type. public static let Custom = ContextSubType(500) } diff --git a/PrebidMobile/AdUnits/Native/ContextType.swift b/PrebidMobile/AdUnits/Native/ContextType.swift index d23cc16bf..6fe0104b7 100644 --- a/PrebidMobile/AdUnits/Native/ContextType.swift +++ b/PrebidMobile/AdUnits/Native/ContextType.swift @@ -15,14 +15,19 @@ import Foundation +/// Native context type asset. @objcMembers public class ContextType: SingleContainerInt { - + + /// Represents a content context type. public static let Content = ContextType(1) - + + /// Represents a social media context type. public static let Social = ContextType(2) + /// Represents a product context type. public static let Product = ContextType(3) + /// Represents a custom context type. public static let Custom = ContextType(500) } diff --git a/PrebidMobile/AdUnits/Native/NativeAd.swift b/PrebidMobile/AdUnits/Native/NativeAd.swift index 39e59b27d..f407df97e 100644 --- a/PrebidMobile/AdUnits/Native/NativeAd.swift +++ b/PrebidMobile/AdUnits/Native/NativeAd.swift @@ -16,12 +16,16 @@ import Foundation import UIKit +/// Represents a native ad and handles its various properties and functionalities. @objcMembers public class NativeAd: NSObject, CacheExpiryDelegate { // MARK: - Public properties + /// The native ad markup containing the ad assets. public var nativeAdMarkup: NativeAdMarkup? + + /// The delegate to receive native ad events. public weak var delegate: NativeAdEventDelegate? // MARK: - Internal properties @@ -44,58 +48,73 @@ public class NativeAd: NSObject, CacheExpiryDelegate { // MARK: - Array getters + /// Returns an array of titles from the native ad markup. @objc public var titles: [NativeTitle] { nativeAdMarkup?.assets?.compactMap { return $0.title } ?? [] } + /// Returns an array of data objects from the native ad markup. @objc public var dataObjects: [NativeData] { nativeAdMarkup?.assets?.compactMap { return $0.data } ?? [] } + /// Returns an array of images from the native ad markup. @objc public var images: [NativeImage] { nativeAdMarkup?.assets?.compactMap { return $0.img } ?? [] } + /// Returns an array of event trackers from the native ad markup. @objc public var eventTrackers: [NativeEventTrackerResponse]? { return nativeAdMarkup?.eventtrackers } // MARK: - Filtered array getters + /// Returns an array of data objects filtered by the specified data type. @objc public func dataObjects(of dataType: NativeDataAssetType) -> [NativeData] { dataObjects.filter { $0.type == dataType.rawValue } } + /// Returns an array of images filtered by the specified image type. @objc public func images(of imageType: NativeImageAssetType) -> [NativeImage] { images.filter { $0.type == imageType.rawValue } } // MARK: - Property getters + /// Returns the first title text from the native ad markup. @objc public var title: String? { return titles.first?.text } + /// Returns the URL of the main image from the native ad markup. @objc public var imageUrl: String? { return images(of: .main).first?.url } + /// Returns the URL of the icon image from the native ad markup. @objc public var iconUrl: String? { return images(of: .icon).first?.url } + /// Returns the sponsored by text from the native ad markup. @objc public var sponsoredBy: String? { return dataObjects(of: .sponsored).first?.value } + /// Returns the description text from the native ad markup. @objc public var text: String? { return dataObjects(of: .desc).first?.value } + /// Returns the call-to-action text from the native ad markup. @objc public var callToAction: String? { return dataObjects(of: .ctaText).first?.value } + /// Creates a `NativeAd` instance from the given cache ID. + /// - Parameter cacheId: The cache ID to retrieve the bid response. + /// - Returns: A `NativeAd` instance if successful, otherwise `nil`. public static func create(cacheId: String) -> NativeAd? { guard let bidString = CacheManager.shared.get(cacheId: cacheId), let bidDic = Utils.shared.getDictionaryFromString(bidString) else { @@ -164,7 +183,11 @@ public class NativeAd: NSObject, CacheExpiryDelegate { } } - //MARK: registerView function + /// Registers a view for tracking viewability and click events. + /// - Parameters: + /// - view: The view to register. + /// - clickableViews: An array of views that should be clickable. + /// - Returns: `true` if the view was successfully registered, otherwise `false`. @discardableResult public func registerView(view: UIView?, clickableViews: [UIView]? ) -> Bool { guard let view = view else { diff --git a/PrebidMobile/AdUnits/Native/NativeAdConfiguration.swift b/PrebidMobile/AdUnits/Native/NativeAdConfiguration.swift index 1f1022111..0772c69ce 100644 --- a/PrebidMobile/AdUnits/Native/NativeAdConfiguration.swift +++ b/PrebidMobile/AdUnits/Native/NativeAdConfiguration.swift @@ -15,18 +15,23 @@ import Foundation +/// Represents the configuration for a native ad, including markup and version information. @objc(PBMNativeAdConfiguration) @objcMembers public class NativeAdConfiguration: NSObject { /// Version of the Native Markup version in use. public var version: String = "1.2" + /// The object containing the request details for the native markup. public var markupRequestObject = NativeMarkupRequestObject() + /// Initializes a new instance of `NativeAdMarkup` with default values. public override init() { super.init() } + /// Initializes a new instance of `NativeAdConfiguration` with the specified native parameters. + /// - Parameter nativeParameters: The parameters to configure the native ad. init(nativeParameters: NativeParameters) { version = nativeParameters.version markupRequestObject = NativeMarkupRequestObject(nativeParameters: nativeParameters) diff --git a/PrebidMobile/AdUnits/Native/NativeAdDelegate.swift b/PrebidMobile/AdUnits/Native/NativeAdDelegate.swift index bef76fbe5..fb45812b9 100644 --- a/PrebidMobile/AdUnits/Native/NativeAdDelegate.swift +++ b/PrebidMobile/AdUnits/Native/NativeAdDelegate.swift @@ -15,21 +15,17 @@ limitations under the License. import Foundation -@objc public protocol NativeAdDelegate : AnyObject{ - /** - * A successful Prebid Native ad is returned - * - * @param ad use this instance for displaying - */ - func nativeAdLoaded(ad:NativeAd) - /** - * Prebid Native was not found in the server returned response, - * Please display the ad as regular ways - */ +@objc public protocol NativeAdDelegate : AnyObject { + + /// A successful Prebid Native ad is returned + /// - Parameter: A successful Prebid Native ad is returned + func nativeAdLoaded(ad: NativeAd) + + /// Prebid Native was not found in the server returned response, + /// Please display the ad as regular ways func nativeAdNotFound() - /** - * Prebid Native ad was returned, however, the bid is not valid for displaying - * Should be treated as on ad load failed - */ + + /// Prebid Native ad was returned, however, the bid is not valid for displaying + /// Should be treated as on ad load failed func nativeAdNotValid() } diff --git a/PrebidMobile/AdUnits/Native/NativeAdEventDelegate.swift b/PrebidMobile/AdUnits/Native/NativeAdEventDelegate.swift index 9e0d1b971..3da904550 100644 --- a/PrebidMobile/AdUnits/Native/NativeAdEventDelegate.swift +++ b/PrebidMobile/AdUnits/Native/NativeAdEventDelegate.swift @@ -15,17 +15,17 @@ limitations under the License. import Foundation -@objc public protocol NativeAdEventDelegate : AnyObject { - /** - * Sent when the native ad is expired. - */ +/// A protocol for handling events related to native ads. +/// +/// This protocol defines optional methods that can be implemented to handle various events associated with native ads, such as expiration, clicks, and impressions. Implementing this protocol allows for custom handling of these events within the native ad lifecycle. +@objc public protocol NativeAdEventDelegate: AnyObject { + + /// Sent when the native ad is expired. @objc optional func adDidExpire(ad:NativeAd) - /** - * Sent when the native view is clicked by the user. - */ + + /// Sent when the native view is clicked by the user. @objc optional func adWasClicked(ad:NativeAd) - /** - * Sent when an impression is recorded for an native ad - */ + + /// Sent when an impression is recorded for an native ad @objc optional func adDidLogImpression(ad:NativeAd) } diff --git a/PrebidMobile/AdUnits/Native/NativeAdMarkup.swift b/PrebidMobile/AdUnits/Native/NativeAdMarkup.swift index c263bf53d..9b9b678f4 100644 --- a/PrebidMobile/AdUnits/Native/NativeAdMarkup.swift +++ b/PrebidMobile/AdUnits/Native/NativeAdMarkup.swift @@ -15,6 +15,7 @@ import Foundation +/// Represents the markup for a native ad, including assets, tracking URLs, and other metadata. @objcMembers public class NativeAdMarkup: NSObject, JsonDecodable { @@ -66,6 +67,8 @@ public class NativeAdMarkup: NSObject, JsonDecodable { /// This object is a placeholder that may contain custom JSON agreed to by the parties to support flexibility beyond the standard defined in this specification public var ext: [String: Any]? + /// Initializes a new instance of `NativeAdMarkup` from a JSON string. + /// - Parameter jsonString: A JSON string representing the native ad markup. convenience public init?(jsonString: String?) { guard let jsonString = jsonString, !jsonString.isEmpty else { Log.warn("The native ad markup json string is empty") @@ -80,6 +83,8 @@ public class NativeAdMarkup: NSObject, JsonDecodable { self.init(jsonDictionary: jsonDic) } + /// Initializes a new instance of `NativeAdMarkup` from a JSON dictionary. + /// - Parameter jsonDictionary: A dictionary representing the native ad markup. public required init(jsonDictionary: [String: Any]) { guard !jsonDictionary.isEmpty else { Log.warn("The native ad markup json dicitonary is empty") @@ -120,6 +125,7 @@ public class NativeAdMarkup: NSObject, JsonDecodable { } } + /// Initializes a new instance of `NativeAdMarkup` with default values. public override init() { super.init() } diff --git a/PrebidMobile/AdUnits/Native/NativeAdMarkupAsset.swift b/PrebidMobile/AdUnits/Native/NativeAdMarkupAsset.swift index ab64ce3ec..488e2a752 100644 --- a/PrebidMobile/AdUnits/Native/NativeAdMarkupAsset.swift +++ b/PrebidMobile/AdUnits/Native/NativeAdMarkupAsset.swift @@ -15,6 +15,7 @@ import Foundation +/// Represents an asset in the native ad markup, which can be a title, image, data, or link. @objcMembers public class NativeAdMarkupAsset: NSObject, JsonDecodable { @@ -44,6 +45,8 @@ public class NativeAdMarkupAsset: NSObject, JsonDecodable { /// flexibility beyond the standard defined in this specification public var ext: [String: Any]? + /// Initializes a new instance of `NativeAdMarkupAsset` from a JSON dictionary. + /// - Parameter jsonDictionary: A dictionary representing the asset in the native ad markup. public required init(jsonDictionary: [String: Any]) { guard !jsonDictionary.isEmpty else { Log.warn("The native title json dicitonary is empty") @@ -67,6 +70,7 @@ public class NativeAdMarkupAsset: NSObject, JsonDecodable { } } + /// Initializes a new instance of `NativeAdMarkupAsset` with default values. public override init() { super.init() } diff --git a/PrebidMobile/AdUnits/Native/NativeAsset.swift b/PrebidMobile/AdUnits/Native/NativeAsset.swift index 6b53c5818..6aa723f10 100644 --- a/PrebidMobile/AdUnits/Native/NativeAsset.swift +++ b/PrebidMobile/AdUnits/Native/NativeAsset.swift @@ -15,16 +15,25 @@ limitations under the License. import UIKit +/// Represents a generic native ad asset which could be a title, image, or data. public class NativeAsset: NSObject { + /// Unique identifier for the asset. var id: NSInteger! - public var required: Bool = false + /// Indicates whether the asset is required for the ad to be considered valid. + public var required: Bool = false + + /// Initializes a new instance of `NativeAsset`. + /// - Parameter isRequired: A boolean indicating whether the asset is required. public init(isRequired: Bool) { super.init() required = isRequired } + /// Generates a dictionary representation of the asset object. + /// - Parameter id: An optional identifier to be included in the asset dictionary. + /// - Returns: A dictionary representing the asset with its properties. func getAssetObject(id : Int) -> [AnyHashable: Any] { var asset: [AnyHashable: Any] = [:] @@ -46,17 +55,26 @@ public class NativeAsset: NSObject { } +/// Represents a title asset in a native ad. @objcMembers public class NativeAssetTitle: NativeAsset { + /// Maximum length of the title. var length: NSInteger! = 25 + /// Additional custom properties for the title asset. public var ext: AnyObject? + /// Initializes a new instance of `NativeAssetTitle`. + /// - Parameters: + /// - length: The maximum length of the title. + /// - required: A boolean indicating whether the asset is required. public required init(length: NSInteger, required: Bool) { super.init(isRequired: required) self.length = length } + /// Generates a dictionary representation of the title asset object. + /// - Returns: A dictionary representing the title asset with its properties. func getTitleObject() -> [AnyHashable: Any] { var title: [AnyHashable: Any] = [:] @@ -65,29 +83,52 @@ public class NativeAsset: NSObject { return title } - } +/// Represents an image asset in a native ad. @objcMembers public class NativeAssetImage: NativeAsset { + /// The type of the image asset. public var type: ImageAsset? + + /// The width of the image asset. public var width: Int? + + /// The minimum width of the image asset. public var widthMin: Int? + + /// The height of the image asset. public var height: Int? + + /// The minimum height of the image asset. public var heightMin: Int? + + /// The MIME types supported for the image asset. public var mimes: Array? + + /// Additional custom properties for the image asset. public var ext: AnyObject? + /// Initializes a new instance of `NativeAssetImage`. + /// - Parameters: + /// - minimumWidth: The minimum width of the image. + /// - minimumHeight: The minimum height of the image. + /// - required: A boolean indicating whether the asset is required. public convenience init(minimumWidth: Int, minimumHeight: Int, required: Bool) { self.init(isRequired: required) self.widthMin = minimumWidth self.heightMin = minimumHeight } + /// Initializes a new instance of `NativeAssetImage`. + /// - Parameters: + /// - isRequired: A boolean indicating whether the asset is required. public override init(isRequired: Bool) { super.init(isRequired: isRequired) } + /// Generates a dictionary representation of the image asset object. + /// - Returns: A dictionary representing the image asset with its properties. func getImageObject() -> [AnyHashable: Any] { var image: [AnyHashable: Any] = [:] @@ -102,19 +143,31 @@ public class NativeAsset: NSObject { return image } - } +/// Represents a data asset in a native ad. @objcMembers public class NativeAssetData: NativeAsset { + + /// The type of the data asset. var type: DataAsset? + + /// The length of the data asset. public var length: Int? + + /// Additional custom properties for the data asset. public var ext: AnyObject? + /// Initializes a new instance of `NativeAssetData`. + /// - Parameters: + /// - type: The type of the data asset. + /// - required: A boolean indicating whether the asset is required. public required init(type: DataAsset, required: Bool) { super.init(isRequired: required) self.type = type } + /// Generates a dictionary representation of the data asset object. + /// - Returns: A dictionary representing the data asset with its properties. func getDataObject() -> [AnyHashable: Any]{ var data: [AnyHashable: Any] = [:] @@ -126,21 +179,25 @@ public class NativeAsset: NSObject { } } +/// Native image asset type. public class ImageAsset: SingleContainerInt { + /// Represents an icon image asset. @objc public static let Icon = ImageAsset(1) + /// Represents the main image asset. @objc public static let Main = ImageAsset(3) + /// Represents a custom image asset. @objc - public static let Custom = ContextType(500) - + public static let Custom = ImageAsset(500) } - +/// Enum representing different types of native data assets. @objc public enum DataAsset: Int { + case sponsored = 1 case description = 2 case rating = 3 @@ -153,22 +210,25 @@ public class ImageAsset: SingleContainerInt { case description2 = 10 case displayurl = 11 case ctatext = 12 + /// Custom type for user-defined data assets case Custom private static var customValue = 500 - - public var exchangeID:Int { - get { - switch self { - case .Custom: - return DataAsset.customValue - default: - return self.rawValue - } - } - set { - DataAsset.customValue = newValue + + /// Gets or sets the exchange ID for the asset type. + /// - Returns: The exchange ID for the asset type. + public var exchangeID:Int { + get { + switch self { + case .Custom: + return DataAsset.customValue + default: + return self.rawValue } - } + set { + DataAsset.customValue = newValue + } + + } } diff --git a/PrebidMobile/AdUnits/Native/NativeData.swift b/PrebidMobile/AdUnits/Native/NativeData.swift index 727c2b0bc..5a01db4da 100644 --- a/PrebidMobile/AdUnits/Native/NativeData.swift +++ b/PrebidMobile/AdUnits/Native/NativeData.swift @@ -15,8 +15,10 @@ import Foundation +/// Class representing native data elements in the ad markup. @objcMembers public class NativeData: NSObject, JsonDecodable { + /// The type of data element being submitted from the Data Asset Types table. /// Required for assetsurl/dcourl responses, not required for embedded asset responses. public var type: Int? @@ -34,6 +36,8 @@ public class NativeData: NSObject, JsonDecodable { /// flexibility beyond the standard defined in this specification public var ext: [String: Any]? + /// Initializes a new `NativeData` object with the provided JSON dictionary. + /// - Parameter jsonDictionary: A dictionary containing the JSON data to initialize the object. public required init(jsonDictionary: [String: Any]) { guard !jsonDictionary.isEmpty else { Log.warn("The native data json dicitonary is empty") diff --git a/PrebidMobile/AdUnits/Native/NativeDataAssetType.swift b/PrebidMobile/AdUnits/Native/NativeDataAssetType.swift index c2e1a498d..991ee9383 100644 --- a/PrebidMobile/AdUnits/Native/NativeDataAssetType.swift +++ b/PrebidMobile/AdUnits/Native/NativeDataAssetType.swift @@ -15,20 +15,36 @@ import Foundation +/// Enum representing various types of native data assets that can be used in ads. +/// +/// Each case represents a different type of data that can be provided in a native ad response. +/// Values are defined according to the type of data they represent, such as descriptive text, ratings, or pricing information. @objc public enum NativeDataAssetType: Int { case undefined = 0 - case sponsored = 1 /// Sponsored By message where response should contain the brand name of the sponsor. - case desc = 2 /// Descriptive text associated with the product or service being advertised. Longer length of text in response may be truncated or ellipsed by the exchange. - case rating = 3 /// Rating of the product being offered to the user. For example an app’s rating in an app store from 0-5. - case likes = 4 /// Number of social ratings or “likes” of the product being offered to the user. - case downloads = 5 /// Number downloads/installs of this product - case price = 6 /// Price for product / app / in-app purchase. Value should include currency symbol in localised format. - case salePrice = 7 /// Sale price that can be used together with price to indicate a discounted price compared to a regular price. Value should include currency symbol in localised format. - case phone = 8 /// Phone number - case address = 9 /// Address - case desc2 = 10 /// Additional descriptive text associated text with the product or service being advertised - case displayURL = 11 /// Display URL for the text ad. To be used when sponsoring entity doesn’t own the content. IE sponsored by BRAND on SITE (where SITE is transmitted in this field). - case ctaText = 12 /// CTA description - descriptive text describing a ‘call to action’ button for the destination URL. - - case custom = 500 /// Reserved for Exchange specific usage numbered above 500 + /// Sponsored By message where response should contain the brand name of the sponsor. + case sponsored = 1 + /// Descriptive text associated with the product or service being advertised. Longer length of text in response may be truncated or ellipsed by the exchange. + case desc = 2 + /// Rating of the product being offered to the user. For example an app’s rating in an app store from 0-5. + case rating = 3 + /// Number of social ratings or “likes” of the product being offered to the user. + case likes = 4 + /// Number downloads/installs of this product + case downloads = 5 + /// Price for product / app / in-app purchase. Value should include currency symbol in localised format. + case price = 6 + /// Sale price that can be used together with price to indicate a discounted price compared to a regular price. Value should include currency symbol in localised format. + case salePrice = 7 + /// Phone number + case phone = 8 + /// Address + case address = 9 + /// Additional descriptive text associated text with the product or service being advertised + case desc2 = 10 + /// Display URL for the text ad. To be used when sponsoring entity doesn’t own the content. IE sponsored by BRAND on SITE (where SITE is transmitted in this field). + case displayURL = 11 + /// CTA description - descriptive text describing a ‘call to action’ button for the destination URL. + case ctaText = 12 + /// Reserved for Exchange specific usage numbered above 500 + case custom = 500 } diff --git a/PrebidMobile/AdUnits/Native/NativeEventTracker.swift b/PrebidMobile/AdUnits/Native/NativeEventTracker.swift index 55e2781cb..1fa68bc10 100644 --- a/PrebidMobile/AdUnits/Native/NativeEventTracker.swift +++ b/PrebidMobile/AdUnits/Native/NativeEventTracker.swift @@ -15,18 +15,30 @@ limitations under the License. import UIKit +/// Class representing an event tracker for native ads. @objc public class NativeEventTracker: NSObject { + /// The type of event being tracked. var event: EventType + + /// List of event tracking methods to be used. var methods: Array + + /// Optional custom extensions or metadata. var ext: AnyObject? + /// Initializes a new `NativeEventTracker` instance. + /// - Parameters: + /// - event: The event type to track. + /// - methods: The methods used for tracking the event. @objc public init(event: EventType, methods: Array) { self.event = event self.methods = methods } + /// Returns a dictionary representation of the event tracker. + /// - Returns: A dictionary containing the event type and tracking methods. func getEventTracker() -> [AnyHashable: Any] { var methodsList:[Int] = [] @@ -43,6 +55,7 @@ import UIKit } } +/// Class representing different event types. public class EventType: SingleContainerInt { @objc public static let Impression = EventType(1) @@ -60,14 +73,15 @@ public class EventType: SingleContainerInt { public static let Custom = EventType(500) } - +/// Native event tracking type. public class EventTracking: SingleContainerInt { - @objc - public static let Image = EventTracking(1) - - @objc - public static let js = EventTracking(2) - - @objc - public static let Custom = EventTracking(500) + + /// Represents image-based event tracking. + @objc public static let Image = EventTracking(1) + + /// Represents JavaScript-based event tracking. + @objc public static let js = EventTracking(2) + + /// Represents a custom event tracking method. + @objc public static let Custom = EventTracking(500) } diff --git a/PrebidMobile/AdUnits/Native/NativeEventTrackerResponse.swift b/PrebidMobile/AdUnits/Native/NativeEventTrackerResponse.swift index 48bba7eca..3ec4ed18c 100644 --- a/PrebidMobile/AdUnits/Native/NativeEventTrackerResponse.swift +++ b/PrebidMobile/AdUnits/Native/NativeEventTrackerResponse.swift @@ -15,6 +15,7 @@ import Foundation +/// Class representing a response for a native event tracker. @objcMembers public class NativeEventTrackerResponse: NSObject, JsonDecodable { @@ -37,6 +38,9 @@ public class NativeEventTrackerResponse: NSObject, JsonDecodable { /// This object is a placeholder that may contain custom JSON agreed to by the parties to support flexibility beyond the standard defined in this specification public var ext: [String: Any]? + /// Initializes a `NativeEventTrackerResponse` object from a JSON dictionary. + /// + /// - Parameter jsonDictionary: A dictionary containing the JSON data to initialize the object. public required init(jsonDictionary: [String: Any]) { guard !jsonDictionary.isEmpty else { Log.warn("The native event trackers json dicitonary is empty") @@ -62,6 +66,7 @@ public class NativeEventTrackerResponse: NSObject, JsonDecodable { } } + /// Initializes with default values public override init() { super.init() } diff --git a/PrebidMobile/AdUnits/Native/NativeImage.swift b/PrebidMobile/AdUnits/Native/NativeImage.swift index 0b296ef05..ac3c4e67a 100644 --- a/PrebidMobile/AdUnits/Native/NativeImage.swift +++ b/PrebidMobile/AdUnits/Native/NativeImage.swift @@ -15,8 +15,10 @@ import Foundation +/// Class representing an image asset in a native ad. @objcMembers public class NativeImage: NSObject, JsonDecodable { + /// The type of image element being submitted from the Image Asset Types table. /// Required for assetsurl or dcourl responses, not required for embedded asset responses. public var type: Int? @@ -38,6 +40,9 @@ public class NativeImage: NSObject, JsonDecodable { /// flexibility beyond the standard defined in this specification public var ext: [String: Any]? + /// Initializes a `NativeImage` object from a JSON dictionary. + /// + /// - Parameter jsonDictionary: A dictionary containing the JSON data to initialize the object. public required init(jsonDictionary: [String: Any]) { guard !jsonDictionary.isEmpty else { Log.warn("The native image json dicitonary is empty") @@ -55,6 +60,7 @@ public class NativeImage: NSObject, JsonDecodable { } } + /// Initializes with default values public override init() { super.init() } diff --git a/PrebidMobile/AdUnits/Native/NativeImageAssetType.swift b/PrebidMobile/AdUnits/Native/NativeImageAssetType.swift index 407936648..3f9399b94 100644 --- a/PrebidMobile/AdUnits/Native/NativeImageAssetType.swift +++ b/PrebidMobile/AdUnits/Native/NativeImageAssetType.swift @@ -15,9 +15,18 @@ import Foundation +/// Enum representing various types of native image assets used in ads. +/// +/// Each case corresponds to a different type of image asset that can be used in native ads. +/// Values are defined according to the role or importance of the image in the ad. @objc public enum NativeImageAssetType: Int { + + /// Represents an icon image, which is typically a small image used as a visual representation of the product or service. case icon = 1 + + /// Represents the main image of the ad, which is usually the primary visual element and central to the ad's presentation. case main = 3 + /// Reserved for exchange-specific usage. case custom = 500 } diff --git a/PrebidMobile/AdUnits/Native/NativeLink.swift b/PrebidMobile/AdUnits/Native/NativeLink.swift index 1e11ce0b9..c72832ba5 100644 --- a/PrebidMobile/AdUnits/Native/NativeLink.swift +++ b/PrebidMobile/AdUnits/Native/NativeLink.swift @@ -15,6 +15,7 @@ import Foundation +/// Class representing a link in a native ad. @objcMembers public class NativeLink: NSObject, JsonDecodable { @@ -31,6 +32,9 @@ public class NativeLink: NSObject, JsonDecodable { /// This object is a placeholder that may contain custom JSON agreed to by the parties to support flexibility beyond the standard defined in this specification public var ext: [String: Any]? + /// Initializes a `NativeLink` object from a JSON dictionary. + /// + /// - Parameter jsonDictionary: A dictionary containing the JSON data to initialize the object. public required init(jsonDictionary: [String: Any]) { guard !jsonDictionary.isEmpty else { Log.warn("The native link json dicitonary is empty") @@ -47,6 +51,7 @@ public class NativeLink: NSObject, JsonDecodable { } } + /// Initializes with default values public override init() { super.init() } diff --git a/PrebidMobile/AdUnits/Native/NativeMarkupRequestObject.swift b/PrebidMobile/AdUnits/Native/NativeMarkupRequestObject.swift index bba96b377..a64f7bd3a 100644 --- a/PrebidMobile/AdUnits/Native/NativeMarkupRequestObject.swift +++ b/PrebidMobile/AdUnits/Native/NativeMarkupRequestObject.swift @@ -15,6 +15,7 @@ import Foundation +/// Represents a request object for native markup, including details about the ad's context, placement, and supported features. @objc(PBMNativeMarkupRequestObject) @objcMembers public class NativeMarkupRequestObject: NSObject, NSCopying, PBMJsonCodable { @@ -70,6 +71,7 @@ public class NativeMarkupRequestObject: NSObject, NSCopying, PBMJsonCodable { /// This object is a placeholder that may contain custom JSON agreed to by the parties to support flexibility beyond the standard defined in this specification public var ext: [String : Any]? + /// Initializes a `NativeMarkupRequestObject` with default values. public override init() { super.init() } @@ -92,6 +94,10 @@ public class NativeMarkupRequestObject: NSObject, NSCopying, PBMJsonCodable { // MARK: - NSCopying + /// Creates a copy of the current `NativeMarkupRequestObject` instance. + /// + /// - Parameter zone: An optional zone for the copy operation. + /// - Returns: A copy of the `NativeMarkupRequestObject` instance. public func copy(with zone: NSZone? = nil) -> Any { let clone = NativeMarkupRequestObject() @@ -112,6 +118,9 @@ public class NativeMarkupRequestObject: NSObject, NSCopying, PBMJsonCodable { // MARK: - PBMJsonCodable + /// Converts the `NativeMarkupRequestObject` instance to a JSON dictionary. + /// + /// - Returns: A dictionary representation of the `NativeMarkupRequestObject` instance. public var jsonDictionary: [String : Any]? { var json = [String : Any]() @@ -130,6 +139,10 @@ public class NativeMarkupRequestObject: NSObject, NSCopying, PBMJsonCodable { return json } + /// Converts the `NativeMarkupRequestObject` instance to a JSON string. + /// + /// - Returns: A JSON string representation of the `NativeMarkupRequestObject` instance. + /// - Throws: An error if the conversion to JSON string fails. public func toJsonString() throws -> String { try PBMFunctions.toStringJsonDictionary(jsonDictionary ?? [:]) } diff --git a/PrebidMobile/AdUnits/Native/NativeRequest.swift b/PrebidMobile/AdUnits/Native/NativeRequest.swift index 4c8ecad67..2471be756 100644 --- a/PrebidMobile/AdUnits/Native/NativeRequest.swift +++ b/PrebidMobile/AdUnits/Native/NativeRequest.swift @@ -15,84 +15,112 @@ limitations under the License. import UIKit +/// A class representing a native request for original type of integration. public class NativeRequest: AdUnit { + /// The version of the native ad specification being used. Defaults to "1.2" if not set. public var version: String { get { adUnitConfig.nativeAdConfiguration?.version ?? "1.2" } set { adUnitConfig.nativeAdConfiguration?.version = newValue } } + /// The context in which the ad appears. See `ContextType` for possible values. public var context: ContextType? { get { adUnitConfig.nativeAdConfiguration?.markupRequestObject.context } set { adUnitConfig.nativeAdConfiguration?.markupRequestObject.context = newValue } } + /// A more detailed context in which the ad appears. See `ContextSubType` for possible values. public var contextSubType: ContextSubType? { get { adUnitConfig.nativeAdConfiguration?.markupRequestObject.contextsubtype } set { adUnitConfig.nativeAdConfiguration?.markupRequestObject.contextsubtype = newValue } } + /// The design/format/layout of the ad unit being offered. See `PlacementType` for possible values. public var placementType: PlacementType? { get { adUnitConfig.nativeAdConfiguration?.markupRequestObject.plcmttype } set { adUnitConfig.nativeAdConfiguration?.markupRequestObject.plcmttype = newValue } } + /// The number of identical placements in the ad layout. Defaults to 1 if not set. public var placementCount: Int { get { adUnitConfig.nativeAdConfiguration?.markupRequestObject.plcmtcnt ?? 1 } set { adUnitConfig.nativeAdConfiguration?.markupRequestObject.plcmtcnt = newValue } } + /// The sequence number of the ad. Defaults to 0 if not set. public var sequence: Int { get { adUnitConfig.nativeAdConfiguration?.markupRequestObject.seq ?? 0 } set { adUnitConfig.nativeAdConfiguration?.markupRequestObject.seq = newValue } } + /// An array of `NativeAsset` objects representing the assets required for the native ad request. public var assets: [NativeAsset]? { get { adUnitConfig.nativeAdConfiguration?.markupRequestObject.assets } set { adUnitConfig.nativeAdConfiguration?.markupRequestObject.assets = newValue } } + /// Indicates whether the supply source/impression supports returning an `assetsurl` instead of an asset object. + /// Defaults to 0 if not set. public var asseturlsupport: Int { get { adUnitConfig.nativeAdConfiguration?.markupRequestObject.aurlsupport ?? 0 } set { adUnitConfig.nativeAdConfiguration?.markupRequestObject.aurlsupport = newValue } } + /// Indicates whether the supply source/impression supports returning a `dco` URL instead of an asset object. + /// Defaults to 0 if not set. public var durlsupport: Int { get { adUnitConfig.nativeAdConfiguration?.markupRequestObject.durlsupport ?? 0 } set { adUnitConfig.nativeAdConfiguration?.markupRequestObject.durlsupport = newValue } } + /// An array of `NativeEventTracker` objects specifying the event tracking settings for the native ad. public var eventtrackers: [NativeEventTracker]? { get { self.adUnitConfig.nativeAdConfiguration?.markupRequestObject.eventtrackers } set { self.adUnitConfig.nativeAdConfiguration?.markupRequestObject.eventtrackers = newValue } } + /// Indicates whether the native ad supports a buyer-specific privacy notice. Defaults to 0 if not set. public var privacy: Int { get { self.adUnitConfig.nativeAdConfiguration?.markupRequestObject.privacy ?? 0 } set { self.adUnitConfig.nativeAdConfiguration?.markupRequestObject.privacy = newValue } } + /// A placeholder for custom JSON agreed to by the parties to support flexibility beyond the standard specification. public var ext: [String: Any]? { get { self.adUnitConfig.nativeAdConfiguration?.markupRequestObject.ext } set { self.adUnitConfig.nativeAdConfiguration?.markupRequestObject.ext = newValue } } + /// The configuration ID for the ad unit. public var configId: String { get { adUnitConfig.configId } set { adUnitConfig.configId = newValue } } + /// Initializes a `NativeRequest` with a specified configuration ID. + /// + /// - Parameter configId: The configuration ID for the ad unit. public init(configId: String) { super.init(configId: configId, size: CGSize.zero, adFormats: [.native]) super.adUnitConfig.nativeAdConfiguration = NativeAdConfiguration() } + /// Initializes a `NativeRequest` with a specified configuration ID, assets, and event trackers. + /// + /// - Parameters: + /// - configId: The configuration ID for the ad unit. + /// - assets: An optional array of `NativeAsset` objects. + /// - eventTrackers: An optional array of `NativeEventTracker` objects. public convenience init(configId: String, assets: [NativeAsset]? = nil, eventTrackers: [NativeEventTracker]? = nil) { self.init(configId: configId) self.assets = assets self.eventtrackers = eventTrackers } + /// Adds an array of native assets to the request. If assets already exist, they will be appended. + /// + /// - Parameter assets: An array of `NativeAsset` objects to add. public func addNativeAssets(_ assets: [NativeAsset]) { if self.assets != nil { self.assets?.append(contentsOf: assets) @@ -101,6 +129,9 @@ public class NativeRequest: AdUnit { } } + /// Adds an array of native event trackers to the request. If event trackers already exist, they will be appended. + /// + /// - Parameter eventTrackers: An array of `NativeEventTracker` objects to add. public func addNativeEventTracker(_ eventTrackers: [NativeEventTracker]) { if eventtrackers != nil { self.eventtrackers?.append(contentsOf: eventTrackers) @@ -109,6 +140,9 @@ public class NativeRequest: AdUnit { } } + /// Retrieves the native request object as a JSON dictionary. + /// + /// - Returns: A dictionary representation of the native request object, or `nil` if an error occurs. public func getNativeRequestObject() -> [AnyHashable: Any]? { guard let markup = try? adUnitConfig.nativeAdConfiguration?.markupRequestObject.toJsonString() else { return nil @@ -124,5 +158,4 @@ public class NativeRequest: AdUnit { return native.toJsonDictionary() } - } diff --git a/PrebidMobile/AdUnits/Native/NativeTitle.swift b/PrebidMobile/AdUnits/Native/NativeTitle.swift index 7b17cce05..96eae665c 100644 --- a/PrebidMobile/AdUnits/Native/NativeTitle.swift +++ b/PrebidMobile/AdUnits/Native/NativeTitle.swift @@ -15,6 +15,7 @@ import Foundation +/// Represents the title element in a native ad, including optional text and length. @objcMembers public class NativeTitle: NSObject, JsonDecodable { /// The text associated with the text element. @@ -28,6 +29,9 @@ public class NativeTitle: NSObject, JsonDecodable { /// flexibility beyond the standard defined in this specification public var ext: [String: Any]? + /// Initializes a `NativeTitle` object from a JSON dictionary. + /// + /// - Parameter jsonDictionary: A dictionary containing the JSON representation of the title. public required init(jsonDictionary: [String: Any]) { guard !jsonDictionary.isEmpty else { Log.warn("The native title json dicitonary is empty") @@ -43,6 +47,7 @@ public class NativeTitle: NSObject, JsonDecodable { } } + /// Initializes a `NativeTitle` object with default values. public override init() { super.init() } diff --git a/PrebidMobile/AdUnits/Native/PlacementType.swift b/PrebidMobile/AdUnits/Native/PlacementType.swift index a7bf40da1..0416522c5 100644 --- a/PrebidMobile/AdUnits/Native/PlacementType.swift +++ b/PrebidMobile/AdUnits/Native/PlacementType.swift @@ -15,16 +15,22 @@ import Foundation +/// Represents different types of placements for native ads. @objcMembers public class PlacementType: SingleContainerInt { - + + /// Placement type indicating the ad appears within feed content. public static let FeedContent = PlacementType(1) - + + /// Placement type indicating the ad appears within atomic content. public static let AtomicContent = PlacementType(2) - + + /// Placement type indicating the ad appears outside of content. public static let OutsideContent = PlacementType(3) - + + /// Placement type indicating the ad appears within a recommendation widget. public static let RecommendationWidget = PlacementType(4) - + + /// Placement type for custom placements not predefined in the standard. public static let Custom = PlacementType(500) } diff --git a/PrebidMobile/AdUnits/Parameters/BannerParameters.swift b/PrebidMobile/AdUnits/Parameters/BannerParameters.swift index 50ee6982f..61b5390bc 100644 --- a/PrebidMobile/AdUnits/Parameters/BannerParameters.swift +++ b/PrebidMobile/AdUnits/Parameters/BannerParameters.swift @@ -22,13 +22,18 @@ public class BannerParameters: NSObject { /// List of supported API frameworks for this impression. If an API is not explicitly listed, it is assumed not to be supported. public var api: [Signals.Api]? + /// Min width percentage value for interstitial public var interstitialMinWidthPerc: Int? + + /// Min height percentage value for interstitial public var interstitialMinHeightPerc: Int? + /// Ad sizes of the ad public var adSizes: [CGSize]? // MARK: - Helpers + /// Helper for `api` values public var rawAPI: [Int]? { get { api?.toIntArray() diff --git a/PrebidMobile/AdUnits/Parameters/NativeParameters.swift b/PrebidMobile/AdUnits/Parameters/NativeParameters.swift index 8a15b08bb..b5741c013 100644 --- a/PrebidMobile/AdUnits/Parameters/NativeParameters.swift +++ b/PrebidMobile/AdUnits/Parameters/NativeParameters.swift @@ -15,22 +15,46 @@ limitations under the License. import Foundation +/// Represents parameters for a native ad request, including assets, event trackers, and configuration settings. @objcMembers public class NativeParameters: NSObject { + /// An array of `NativeAsset` objects representing the assets required for the native ad request. public var assets: [NativeAsset]? + + /// An array of `NativeEventTracker` objects specifying the event tracking settings for the native ad. public var eventtrackers: [NativeEventTracker]? + /// The version of the native ad specification being used. Defaults to "1.2". public var version: String = "1.2" + + /// The context in which the ad appears. See `ContextType` for possible values. public var context: ContextType? + + /// A more detailed context in which the ad appears. See `ContextSubType` for possible values. public var contextSubType: ContextSubType? + + /// The design/format/layout of the ad unit being offered. See `PlacementType` for possible values. public var placementType: PlacementType? + + /// The number of identical placements in the ad layout. Defaults to 1. public var placementCount: Int = 1 + + /// The sequence number of the ad. Defaults to 0. public var sequence: Int = 0 + /// Indicates whether the supply source/impression supports returning an `assetsurl` instead of an asset object. + /// Defaults to 0, indicating no support. public var asseturlsupport: Int = 0 + + /// Indicates whether the supply source/impression supports returning a `dco` URL instead of an asset object. + /// Defaults to 0, indicating no support. public var durlsupport: Int = 0 + /// Indicates whether the supply source/impression supports returning a `dco` URL instead of an asset object. + /// Defaults to 0, indicating no support. public var privacy: Int = 0 + + /// A placeholder for custom JSON agreed to by the parties to support flexibility beyond the standard specification. public var ext: [String: Any]? } diff --git a/PrebidMobile/AdUnits/Parameters/Signals.swift b/PrebidMobile/AdUnits/Parameters/Signals.swift index a8231bb90..c1750fff2 100644 --- a/PrebidMobile/AdUnits/Parameters/Signals.swift +++ b/PrebidMobile/AdUnits/Parameters/Signals.swift @@ -15,56 +15,26 @@ limitations under the License. import Foundation -public class SingleContainerInt: NSObject, ExpressibleByIntegerLiteral { - - public typealias IntegerLiteralType = Int - - @objc - public let value: Int - - @objc - public required init(integerLiteral value: Int) { - self.value = value - } - - static func == (lhs: SingleContainerInt, rhs: SingleContainerInt) -> Bool { - return lhs.value == rhs.value - } - - override public func isEqual(_ object: Any?) -> Bool { - - if let other = object as? SingleContainerInt { - if self === other { - return true - } else { - return self.value == other.value - } - } - - return false - - } - - override public var hash : Int { - return value.hashValue - } -} - +/// A class containing constants related to OpenRTB signals. +/// +/// This class provides static constants and values representing different +/// API frameworks, playback methods, protocols, start delays, and video +/// placement types as defined in the OpenRTB specification. +/// public class Signals: NSObject { - /** - # OpenRTB - API Frameworks # - ``` - | Value | Description | - |-------|-------------| - | 1 | VPAID 1.0 | - | 2 | VPAID 2.0 | - | 3 | MRAID-1 | - | 4 | ORMMA | - | 5 | MRAID-2 | - | 6 | MRAID-3 | - | 7 | OMID-1 | - ``` - */ + + ///# OpenRTB - API Frameworks # + /// ``` + /// | Value | Description | + /// |-------|-------------| + /// | 1 | VPAID 1.0 | + /// | 2 | VPAID 2.0 | + /// | 3 | MRAID-1 | + /// | 4 | ORMMA | + /// | 5 | MRAID-2 | + /// | 6 | MRAID-3 | + /// | 7 | OMID-1 | + /// ``` @objc(PBApi) public class Api: SingleContainerInt { @@ -97,19 +67,18 @@ public class Signals: NSObject { public static let OMID_1 = Api(7) } - /** - # OpenRTB - Playback Methods # - ``` - | Value | Description | - |-------|----------------------------------------------------------| - | 1 | Initiates on Page Load with Sound On | - | 2 | Initiates on Page Load with Sound Off by Default | - | 3 | Initiates on Click with Sound On | - | 4 | Initiates on Mouse-Over with Sound On | - | 5 | Initiates on Entering Viewport with Sound On | - | 6 | Initiates on Entering Viewport with Sound Off by Default | - ``` - */ + + /// # OpenRTB - Playback Methods # + /// ``` + /// | Value | Description | + /// |-------|----------------------------------------------------------| + /// | 1 | Initiates on Page Load with Sound On | + /// | 2 | Initiates on Page Load with Sound Off by Default | + /// | 3 | Initiates on Click with Sound On | + /// | 4 | Initiates on Mouse-Over with Sound On | + /// | 5 | Initiates on Entering Viewport with Sound On | + /// | 6 | Initiates on Entering Viewport with Sound Off by Default | + /// ``` @objc(PBPlaybackMethod) public class PlaybackMethod: SingleContainerInt { @@ -139,23 +108,21 @@ public class Signals: NSObject { } - /** - # OpenRTB - Protocols # - ``` - | Value | Description | - |-------|-------------------| - | 1 | VAST 1.0 | - | 2 | VAST 2.0 | - | 3 | VAST 3.0 | - | 4 | VAST 1.0 Wrapper | - | 5 | VAST 2.0 Wrapper | - | 6 | VAST 3.0 Wrapper | - | 7 | VAST 4.0 | - | 8 | VAST 4.0 Wrapper | - | 9 | DAAST 1.0 | - | 10 | DAAST 1.0 Wrapper | - ``` - */ + /// # OpenRTB - Protocols # + /// ``` + /// | Value | Description | + /// |-------|-------------------| + /// | 1 | VAST 1.0 | + /// | 2 | VAST 2.0 | + /// | 3 | VAST 3.0 | + /// | 4 | VAST 1.0 Wrapper | + /// | 5 | VAST 2.0 Wrapper | + /// | 6 | VAST 3.0 Wrapper | + /// | 7 | VAST 4.0 | + /// | 8 | VAST 4.0 Wrapper | + /// | 9 | DAAST 1.0 | + /// | 10 | DAAST 1.0 Wrapper | + /// ``` @objc(PBProtocols) public class Protocols: SingleContainerInt { @@ -201,17 +168,15 @@ public class Signals: NSObject { } - /** - # OpenRTB - Start Delay # - ``` - | Value | Description | - |-------|--------------------------------------------------| - | > 0 | Mid-Roll (value indicates start delay in second) | - | 0 | Pre-Roll | - | -1 | Generic Mid-Roll | - | -2 | Generic Post-Roll | - ``` - */ + /// # OpenRTB - Start Delay # + /// ``` + /// | Value | Description | + /// |-------|--------------------------------------------------| + /// | > 0 | Mid-Roll (value indicates start delay in second) | + /// | 0 | Pre-Roll | + /// | -1 | Generic Mid-Roll | + /// | -2 | Generic Post-Roll | + /// ``` @objc(PBStartDelay) public class StartDelay: SingleContainerInt { @@ -229,18 +194,16 @@ public class Signals: NSObject { } - /** - # OpenRTB - Video Placement Types # - ``` - | Value | Description | - |-------|------------------------------| - | 1 | In-Stream | - | 2 | In-Banner | - | 3 | In-Article | - | 4 | In-Feed | - | 5 | Interstitial/Slider/Floating | - ``` - */ + /// # OpenRTB - Video Placement Types # + /// ``` + /// | Value | Description | + /// |-------|------------------------------| + /// | 1 | In-Stream | + /// | 2 | In-Banner | + /// | 3 | In-Article | + /// | 4 | In-Feed | + /// | 5 | Interstitial/Slider/Floating | + /// ``` @objc(PBPlacement) public class Placement: SingleContainerInt { @@ -272,6 +235,7 @@ public class Signals: NSObject { @objc public static let Floating = Placement(5) + /// Helper function @objc public static func getPlacementByRawValue(_ value: Int) -> Signals.Placement? { switch value { case 1: diff --git a/PrebidMobile/AdUnits/Parameters/SingleContainerInt.swift b/PrebidMobile/AdUnits/Parameters/SingleContainerInt.swift new file mode 100644 index 000000000..1bca11123 --- /dev/null +++ b/PrebidMobile/AdUnits/Parameters/SingleContainerInt.swift @@ -0,0 +1,51 @@ +/* Copyright 2018-2019 Prebid.org, Inc. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +import Foundation + +public class SingleContainerInt: NSObject, ExpressibleByIntegerLiteral { + + public typealias IntegerLiteralType = Int + + @objc + public let value: Int + + @objc + public required init(integerLiteral value: Int) { + self.value = value + } + + static func == (lhs: SingleContainerInt, rhs: SingleContainerInt) -> Bool { + return lhs.value == rhs.value + } + + override public func isEqual(_ object: Any?) -> Bool { + + if let other = object as? SingleContainerInt { + if self === other { + return true + } else { + return self.value == other.value + } + } + + return false + + } + + override public var hash: Int { + return value.hashValue + } +} diff --git a/PrebidMobile/AdUnits/Parameters/VideoParameters.swift b/PrebidMobile/AdUnits/Parameters/VideoParameters.swift index 525a7f5e6..7db51bb7b 100644 --- a/PrebidMobile/AdUnits/Parameters/VideoParameters.swift +++ b/PrebidMobile/AdUnits/Parameters/VideoParameters.swift @@ -34,14 +34,14 @@ public class VideoParameters: NSObject { /// Minimum video ad duration in seconds. public var minDuration: SingleContainerInt? - /** - Content MIME types supported. - Prebid Server required property. + + /// Content MIME types supported. + /// Prebid Server required property. - # Example # - * "video/mp4" - * "video/x-ms-wmv" - */ + /// # Example # + /// "video/mp4" + /// "video/x-ms-wmv" + /// public var mimes: [String] /// Allowed playback methods. If none specified, assume all are allowed. @@ -63,18 +63,21 @@ public class VideoParameters: NSObject { // MARK: - Helpers + /// Helper property public var rawAPI: [Int]? { get { api?.toIntArray() } } + /// Helper property public var rawPlaybackMethod: [Int]? { get { playbackMethod?.toIntArray() } } + /// Helper property public var rawProtocols: [Int]? { get { protocols?.toIntArray() @@ -86,7 +89,7 @@ public class VideoParameters: NSObject { self.mimes = mimes } - // Objective-C API + /// Objective-C API public func setSize(_ size: NSValue) { adSize = size.cgSizeValue } diff --git a/PrebidMobile/AdUnits/RewardedVideoAdUnit.swift b/PrebidMobile/AdUnits/RewardedVideoAdUnit.swift index 236204848..d58e491da 100644 --- a/PrebidMobile/AdUnits/RewardedVideoAdUnit.swift +++ b/PrebidMobile/AdUnits/RewardedVideoAdUnit.swift @@ -15,19 +15,27 @@ limitations under the License. import UIKit +/// Represents an rewarded ad unit for original type of integration. public class RewardedVideoAdUnit: AdUnit, VideoBasedAdUnitProtocol { + /// Deprecated property for video parameters. + /// + /// - Note: This property is deprecated. Please use `videoParameters` instead. @available(*, deprecated, message: "This property is deprecated. Please, use videoParameters instead.") public var parameters: VideoParameters { get { adUnitConfig.adConfiguration.videoParameters } set { adUnitConfig.adConfiguration.videoParameters = newValue } } + /// Property for video parameters. public var videoParameters: VideoParameters { get { adUnitConfig.adConfiguration.videoParameters } set { adUnitConfig.adConfiguration.videoParameters = newValue } } + /// Initializes a `RewardedVideoAdUnit` with the given configuration ID. + /// + /// - Parameter configId: The configuration ID for the ad unit. public init(configId: String) { super.init(configId: configId, size: nil, adFormats: [.video]) adUnitConfig.adConfiguration.isInterstitialAd = true @@ -35,6 +43,11 @@ public class RewardedVideoAdUnit: AdUnit, VideoBasedAdUnitProtocol { adUnitConfig.adConfiguration.videoParameters.placement = .Interstitial } + /// Initializes a `RewardedVideoAdUnit` with the given configuration ID and minimum size percentages. + /// + /// - Parameter configId: The configuration ID for the ad unit. + /// - Parameter minWidthPerc: The minimum width percentage for the ad unit. + /// - Parameter minHeightPerc: The minimum height percentage for the ad unit. public convenience init(configId: String, minWidthPerc: Int, minHeightPerc: Int) { self.init(configId: configId) adUnitConfig.minSizePerc = NSValue(cgSize: CGSize(width: minWidthPerc, height: minHeightPerc)) diff --git a/PrebidMobile/AdUnits/Utils.swift b/PrebidMobile/AdUnits/Utils.swift index 3557858c6..5d1f31361 100644 --- a/PrebidMobile/AdUnits/Utils.swift +++ b/PrebidMobile/AdUnits/Utils.swift @@ -16,20 +16,19 @@ import Foundation import WebKit +/// A utility class for handling various ad-related operations and conversions. public class Utils: NSObject { - /** - * The class is created as a singleton object & used - */ + /// The class is created as a singleton object & used @objc public static let shared = Utils() - /** - * The initializer that needs to be created only once - */ + /// The initializer that needs to be created only once private override init() { super.init() } + + /// A delegate to handle native ad events. @objc public weak var delegate: NativeAdDelegate? @@ -40,6 +39,7 @@ public class Utils: NSObject { private let GAD_CUSTOM_NATIVE_AD = "GADCustomNativeAd" private let INNNER_HTML_SCRIPT = "document.body.innerHTML" + /// Deprecated. MoPub is not available anymore. Use Prebid MAX adapters instead. @available(*, deprecated, message: "MoPub is not available anymore. Use Prebid MAX adapters instead.") @objc public func convertDictToMoPubKeywords(dict: Dictionary) -> String { @@ -241,6 +241,9 @@ public class Utils: NSObject { } } + /// Finds a native ad object within a given object. + /// + /// - Parameter adObject: The object to search within. @objc public func findNative(adObject: AnyObject){ if (self.isObjectFromClass(adObject, DFP_BANNER_VIEW_CLASSNAME)) { @@ -425,10 +428,9 @@ public class Utils: NSObject { } } -/** - 1. It is a class that allow use it as AnyObject and passs to - func fetchDemand(adObject: AnyObject, ...) - 2. It is not a public class as a result client can not directly pass it to - func fetchDemand(adObject: AnyObject, ...) - */ + +/// 1. It is a class that allow use it as AnyObject and passs to - func fetchDemand(adObject: AnyObject, ...) +/// 2. It is not a public class as a result client can not directly pass it to - func fetchDemand(adObject: AnyObject, ...) class DictionaryContainer { var dict = [T1 : T2]() } diff --git a/PrebidMobile/AdUnits/VideoAdUnit.swift b/PrebidMobile/AdUnits/VideoAdUnit.swift index 8b205b0b8..06e9a8367 100644 --- a/PrebidMobile/AdUnits/VideoAdUnit.swift +++ b/PrebidMobile/AdUnits/VideoAdUnit.swift @@ -15,18 +15,28 @@ import UIKit +/// A deprecated class for handling video ad units. @available(*, deprecated, message: "This class is deprecated. Please, use BannerAdUnit with video adFormat.") public class VideoAdUnit: AdUnit { + /// The parameters for video ads associated with this ad unit. public var parameters: VideoParameters { get { adUnitConfig.adConfiguration.videoParameters } set { adUnitConfig.adConfiguration.videoParameters = newValue } } + /// Initializes a new instance of `VideoAdUnit` with the specified configuration ID and size. + /// + /// - Parameters: + /// - configId: The configuration ID for the ad unit. + /// - size: The size of the ad unit. public init(configId: String, size: CGSize) { super.init(configId: configId, size: size, adFormats: [.video]) } + /// Adds additional sizes to the ad unit. + /// + /// - Parameter sizes: An array of `CGSize` objects representing the additional sizes for the ad unit. public func addAdditionalSize(sizes: [CGSize]) { if super.adUnitConfig.additionalSizes == nil { super.adUnitConfig.additionalSizes = [CGSize]() diff --git a/PrebidMobile/AdUnits/VideoInterstitialAdUnit.swift b/PrebidMobile/AdUnits/VideoInterstitialAdUnit.swift index ecff952ee..9c1659158 100644 --- a/PrebidMobile/AdUnits/VideoInterstitialAdUnit.swift +++ b/PrebidMobile/AdUnits/VideoInterstitialAdUnit.swift @@ -15,14 +15,22 @@ import UIKit +/// A deprecated class representing a video interstitial ad unit. +/// This class is used to configure and manage video interstitial ads. It inherits from `AdUnit` and provides +/// specific settings for video ads including interstitial ad configuration and placement. @available(*, deprecated, message: "This class is deprecated. Please, use InterstitialAdUnit with video adFormat.") public class VideoInterstitialAdUnit: AdUnit { + /// The video parameters for this ad unit. + /// This property allows you to get or set the video parameters for the ad unit's configuration. public var parameters: VideoParameters { get { adUnitConfig.adConfiguration.videoParameters } set { adUnitConfig.adConfiguration.videoParameters = newValue } } + /// Initializes a new instance of `VideoInterstitialAdUnit` with the specified configuration ID. + /// The ad unit is configured as an interstitial ad with full screen placement and video parameters set for interstitial ads. + /// - Parameter configId: The configuration ID for the ad unit. public init(configId: String) { super.init(configId: configId, size: nil, adFormats: [.video]) @@ -31,6 +39,11 @@ public class VideoInterstitialAdUnit: AdUnit { adUnitConfig.adConfiguration.videoParameters.placement = .Interstitial } + /// Convenience initializer to create a video interstitial ad unit with specified minimum width and height percentages. + /// - Parameters: + /// - configId: The configuration ID for the ad unit. + /// - minWidthPerc: The minimum width percentage of the ad unit. + /// - minHeightPerc: The minimum height percentage of the ad unit. public convenience init(configId: String, minWidthPerc: Int, minHeightPerc: Int) { self.init(configId: configId) diff --git a/PrebidMobile/ConfigurationAndTargeting/Gender.swift b/PrebidMobile/ConfigurationAndTargeting/Gender.swift index 556c57f23..e9617b729 100644 --- a/PrebidMobile/ConfigurationAndTargeting/Gender.swift +++ b/PrebidMobile/ConfigurationAndTargeting/Gender.swift @@ -15,11 +15,26 @@ import Foundation +/// An enumeration representing gender options for ad targeting or other purposes. +/// This enum is used to specify different gender options and is intended for use in contexts where gender information may be relevant. +/// +/// - `unknown`: Gender is not specified or unknown. +/// - `male`: Represents the male gender. +/// - `female`: Represents the female gender. +/// - `other`: Represents any other gender that does not fit into the male or female categories. @objc(PBMGender) public enum Gender : Int { + + /// Gender is not specified or unknown. case unknown + + /// Represents the male gender. case male + + /// Represents the female gender. case female + + /// Represents any other gender that does not fit into the male or female categories. case other } diff --git a/PrebidMobile/ConfigurationAndTargeting/Prebid.swift b/PrebidMobile/ConfigurationAndTargeting/Prebid.swift index 9ac243f50..db6438197 100644 --- a/PrebidMobile/ConfigurationAndTargeting/Prebid.swift +++ b/PrebidMobile/ConfigurationAndTargeting/Prebid.swift @@ -17,61 +17,74 @@ import Foundation fileprivate let defaultTimeoutMillis = 2000 +/// A callback used for Prebid initialization status. +/// +/// This callback is called when the Prebid SDK initialization completes. It provides the status of the initialization and any error that may have occurred. +/// +/// - Parameters: +/// - status: The status of the Prebid initialization. +/// - error: An optional error that occurred during initialization. public typealias PrebidInitializationCallback = ((PrebidInitializationStatus, Error?) -> Void) +/// The `Prebid` class manages the configuration and initialization of the PrebidMobile SDK. @objcMembers public class Prebid: NSObject { // MARK: - Public Properties (SDK) + /// The name of the bidder for AppNexus. public static let bidderNameAppNexus = "appnexus" + + /// The name of the bidder for Rubicon Project. public static let bidderNameRubiconProject = "rubicon" + /// Indicates whether the timeout value has been updated. public var timeoutUpdated: Bool = false + /// The Prebid Server account ID. public var prebidServerAccountId = "" + /// Enables or disables debug mode. + /// ORTB: bidRequest.test public var pbsDebug = false + /// Custom HTTP headers to be sent with requests. public var customHeaders: [String: String] = [:] + /// Stored bid responses identified by bidder names. public var storedBidResponses: [String: String] = [:] - /** - * This property is set by the developer when he is willing to assign the assetID for Native ad. - **/ + /// This property is set by the developer when he is willing to assign the assetID for Native ad. public var shouldAssignNativeAssetID : Bool = false - /** - * This property is set by the developer when he is willing to share the location for better ad targeting - **/ + /// This property is set by the developer when he is willing to share the location for better ad targeting public var shareGeoLocation = false - /** - * Set the desidered verbosity of the logs - */ + /// Set the desidered verbosity of the logs public var logLevel: LogLevel { get { Log.logLevel } set { Log.logLevel = newValue } } - /** - * Array containing objects that hold External UserId parameters. - */ + /// Array containing objects that hold External UserId parameters. public var externalUserIdArray = [ExternalUserId]() + /// The singleton instance of the `Prebid` class. public static let shared = Prebid() + /// The version of the PrebidMobile SDK. public var version: String { PBMFunctions.sdkVersion() } + /// The version of the OM SDK. public var omsdkVersion: String { OMSDKVersionProvider.omSDKVersionString } // MARK: - Public Properties (Prebid) + /// The host for the Prebid Server. public var prebidServerHost: PrebidHost = .Custom { didSet { timeoutMillisDynamic = NSNumber(value: timeoutMillis) @@ -79,62 +92,69 @@ public class Prebid: NSObject { } } + /// Custom status endpoint for the Prebid Server. public var customStatusEndpoint: String? { didSet { PrebidSDKInitializer.setCustomStatusEndpoint(customStatusEndpoint) } } + /// Timeout for Prebid requests in milliseconds. public var timeoutMillis: Int { didSet { timeoutMillisDynamic = NSNumber(value: timeoutMillis) } } + /// Dynamic timeout value. public var timeoutMillisDynamic: NSNumber? + /// Stored auction response. public var storedAuctionResponse: String? // MARK: - Public Properties (SDK) - //Indicates whether the PBS should cache the bid for the rendering API. - //If the value is true the SDK will make the cache request in order to report - //the impression event respectively to the legacy analytic setup. + /// Indicates whether the PBS should cache the bid for the rendering API. + /// If the value is true the SDK will make the cache request in order to report + /// the impression event respectively to the legacy analytic setup. public var useCacheForReportingWithRenderingAPI = false - //Controls how long each creative has to load before it is considered a failure. + /// Controls how long each creative has to load before it is considered a failure. public var creativeFactoryTimeout: TimeInterval = 6.0 - //Controls how long video and interstitial creatives have to load before it is considered a failure. + /// Controls how long video and interstitial creatives have to load before it is considered a failure. public var creativeFactoryTimeoutPreRenderContent: TimeInterval = 30.0 - //Controls whether to use PrebidMobile's in-app browser or the Safari App for displaying ad clickthrough content. + /// Controls whether to use PrebidMobile's in-app browser or the Safari App for displaying ad clickthrough content. public var useExternalClickthroughBrowser = false - //Indicates the type of browser opened upon clicking the creative in an app, where embedded = 0, native = 1. - //Describes an [OpenRTB](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf) imp.clickbrowser attribute. + /// Indicates the type of browser opened upon clicking the creative in an app, where embedded = 0, native = 1. + /// Describes an [OpenRTB](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf) imp.clickbrowser attribute. public var impClickbrowserType: ClickbrowserType = .native - //If set to true, the output of PrebidMobile's internal logger is written to a text file. This can be helpful for debugging. Defaults to false. + /// If set to true, the output of PrebidMobile's internal logger is written to a text file. This can be helpful for debugging. Defaults to false. public var debugLogFileEnabled: Bool { get { Log.logToFile } set { Log.logToFile = newValue } } - //If true, the SDK will periodically try to listen for location updates in order to request location-based ads. + /// If true, the SDK will periodically try to listen for location updates in order to request location-based ads. public var locationUpdatesEnabled: Bool { get { PBMLocationManager.shared.locationUpdatesEnabled } set { PBMLocationManager.shared.locationUpdatesEnabled = newValue } } - //If true, the sdk will add `includewinners` flag inside the targeting object described in [PBS Documentation](https://docs.prebid.org/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#targeting) + /// If true, the sdk will add `includewinners` flag inside the targeting object described in [PBS Documentation](https://docs.prebid.org/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#targeting) public var includeWinners = false - //If true, the sdk will add `includebidderkeys` flag inside the targeting object described in [PBS Documentation](https://docs.prebid.org/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#targeting) + /// If true, the sdk will add `includebidderkeys` flag inside the targeting object described in [PBS Documentation](https://docs.prebid.org/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#targeting) public var includeBidderKeys = false // MARK: - Public Methods + /// Sets a custom Prebid Server URL. + /// - Parameter url: The custom Prebid Server URL. + /// - Throws: An error if setting the custom host URL fails. public func setCustomPrebidServer(url: String) throws { prebidServerHost = .Custom try Host.shared.setCustomHostURL(url) @@ -142,14 +162,21 @@ public class Prebid: NSObject { // MARK: - Stored Bid Response + /// Adds a stored bid response. + /// - Parameters: + /// - bidder: The name of the bidder. + /// - responseId: The response ID. public func addStoredBidResponse(bidder: String, responseId: String) { storedBidResponses[bidder] = responseId } + /// Clears all stored bid responses. public func clearStoredBidResponses() { storedBidResponses.removeAll() } + /// Retrieves stored bid responses. + /// - Returns: An array of dictionaries containing stored bid responses, or nil if there are none. public func getStoredBidResponses() -> [[String: String]]? { var storedBidResponses: [[String: String]] = [] @@ -164,10 +191,15 @@ public class Prebid: NSObject { // MARK: - Custom Headers + /// Adds a custom HTTP header. + /// - Parameters: + /// - name: The name of the header. + /// - value: The value of the header. public func addCustomHeader(name: String, value: String) { customHeaders[name] = value } + /// Clears all custom HTTP headers. public func clearCustomHeaders() { customHeaders.removeAll() } diff --git a/PrebidMobile/ConfigurationAndTargeting/PrebidGAMVersionChecker.swift b/PrebidMobile/ConfigurationAndTargeting/PrebidGAMVersionChecker.swift index b7948dfb7..2867036da 100644 --- a/PrebidMobile/ConfigurationAndTargeting/PrebidGAMVersionChecker.swift +++ b/PrebidMobile/ConfigurationAndTargeting/PrebidGAMVersionChecker.swift @@ -18,7 +18,7 @@ import Foundation class PrebidGAMVersionChecker { var latestTestedGMAVersion: (Int, Int, Int) { - (11, 8, 0) + (11, 10, 0) } var currentGMAVersion: (Int, Int, Int)? diff --git a/PrebidMobile/ConfigurationAndTargeting/PrebidInitializationStatus.swift b/PrebidMobile/ConfigurationAndTargeting/PrebidInitializationStatus.swift index c90fb2670..6d67333b8 100644 --- a/PrebidMobile/ConfigurationAndTargeting/PrebidInitializationStatus.swift +++ b/PrebidMobile/ConfigurationAndTargeting/PrebidInitializationStatus.swift @@ -15,6 +15,9 @@ import Foundation +/// Enum representing the initialization status of the Prebid SDK. +/// +/// This enum provides various statuses that indicate the result of the Prebid SDK initialization process. It helps in understanding whether the SDK was successfully initialized or if there were issues during the initialization. @objc public enum PrebidInitializationStatus: Int { /// Prebid SDK successfully initialized. case succeeded diff --git a/PrebidMobile/ConfigurationAndTargeting/Targeting.swift b/PrebidMobile/ConfigurationAndTargeting/Targeting.swift index 8d46e5333..a45879c71 100644 --- a/PrebidMobile/ConfigurationAndTargeting/Targeting.swift +++ b/PrebidMobile/ConfigurationAndTargeting/Targeting.swift @@ -22,30 +22,37 @@ fileprivate let PrebidTargetingKey_GENDER = "gen" fileprivate let PrebidTargetingKey_USER_ID = "xid" fileprivate let PrebidTargetingKey_PUB_PROVIDED_PREFIX = "c." + +/// A class that manages targeting information for ads. +/// +/// This class provides properties and methods for setting and retrieving +/// user-specific targeting information, such as user ID, gender, and custom +/// data. It also includes details for OMID (Open Measurement Interface Definition) +/// partner and supports managing user identity links and custom extensions. +/// @objcMembers public class Targeting: NSObject { + /// A shared instance of the `Targeting` class. public static var shared = Targeting() // MARK: - OMID Partner + /// The name of the OMID partner. public var omidPartnerName: String? + /// The version of the OMID partner. public var omidPartnerVersion: String? // MARK: - User Information - /** - Indicates user birth year. - */ + /// Indicates user birth year. public var yearOfBirth: Int { get { yearofbirth } set { setYearOfBirth(yob: newValue) } } - /** - * This method set the year of birth value - */ + /// This method set the year of birth value public func setYearOfBirth(yob: Int) { if AgeUtils.isYOBValid(yob) { yearofbirth = yob @@ -54,21 +61,17 @@ public class Targeting: NSObject { } } - // Objective C API + /// Objective C API public func getYearOfBirth() -> NSNumber { NSNumber(value: yearOfBirth) } - /** - * This method clears year of birth value set by the application developer - */ + /// This method clears year of birth value set by the application developer public func clearYearOfBirth() { yearofbirth = 0 } - /** - Indicates the end-user's gender. - */ + /// Indicates the end-user's gender. public var userGender: Gender { get { guard let currentValue = parameterDictionary[PrebidTargetingKey_GENDER] else { @@ -83,10 +86,8 @@ public class Targeting: NSObject { } } - /** - String representation of the users gender, - where “M” = male, “F” = female, “O” = known to be other (i.e., omitted is unknown) - */ + /// String representation of the users gender, + /// where “M” = male, “F” = female, “O” = known to be other (i.e., omitted is unknown) public func userGenderDescription() -> String? { guard let currentValue = parameterDictionary[PrebidTargetingKey_GENDER] else { return nil @@ -95,52 +96,39 @@ public class Targeting: NSObject { return GenderDescription(rawValue: currentValue)?.rawValue } - /** - Indicates the customer-provided user ID, if different from the Device ID. - */ + /// Indicates the customer-provided user ID, if different from the Device ID. public var userID: String? { get { parameterDictionary[PrebidTargetingKey_USER_ID] } set { parameterDictionary[PrebidTargetingKey_USER_ID] = newValue } } - /** - Buyer-specific ID for the user as mapped by the exchange for the buyer. - */ + /// Buyer-specific ID for the user as mapped by the exchange for the buyer. public var buyerUID: String? - /** - Optional feature to pass bidder data that was set in the - exchange’s cookie. The string must be in base85 cookie safe - characters and be in any format. Proper JSON encoding must - be used to include “escaped” quotation marks. - */ + + /// Optional feature to pass bidder data that was set in the + /// exchange’s cookie. The string must be in base85 cookie safe + /// characters and be in any format. Proper JSON encoding must + /// be used to include “escaped” quotation marks. public var userCustomData: String? - /** - Placeholder for User Identity Links. - The data from this property will be added to usr.ext.eids - */ + /// Placeholder for User Identity Links. + /// The data from this property will be added to usr.ext.eids public var eids: [[String : AnyHashable]]? - /** - Placeholder for exchange-specific extensions to OpenRTB. - */ + /// Placeholder for exchange-specific extensions to OpenRTB. public var userExt: [String : AnyHashable]? // MARK: - COPPA - /** - Objective C analog of subjectToCOPPA - */ + /// Objective C analog of subjectToCOPPA public var coppa: NSNumber? { set { UserConsentDataManager.shared.subjectToCOPPA = newValue.boolValue } get { UserConsentDataManager.shared.subjectToCOPPA.nsNumberValue } } - /** - Integer flag indicating if this request is subject to the COPPA regulations - established by the USA FTC, where 0 = no, 1 = yes - */ + /// Integer flag indicating if this request is subject to the COPPA regulations + /// established by the USA FTC, where 0 = no, 1 = yes public var subjectToCOPPA: Bool? { set { UserConsentDataManager.shared.subjectToCOPPA = newValue} get { UserConsentDataManager.shared.subjectToCOPPA } @@ -148,28 +136,26 @@ public class Targeting: NSObject { // MARK: - GDPR - /** - * The boolean value set by the user to collect user data - */ + /// The boolean value set by the user to collect user data public var subjectToGDPR: Bool? { set { UserConsentDataManager.shared.subjectToGDPR = newValue } get { UserConsentDataManager.shared.subjectToGDPR } } + /// Objective-C API public func setSubjectToGDPR(_ newValue: NSNumber?) { UserConsentDataManager.shared.subjectToGDPR = newValue?.boolValue } + /// Objective-C API public func getSubjectToGDPR() -> NSNumber? { return UserConsentDataManager.shared.subjectToGDPR_NSNumber } // MARK: - GDPR Consent - /** - * The consent string for sending the GDPR consent - */ + /// The consent string for sending the GDPR consent public var gdprConsentString: String? { set { UserConsentDataManager.shared.gdprConsentString = newValue } get { UserConsentDataManager.shared.gdprConsentString } @@ -177,37 +163,40 @@ public class Targeting: NSObject { // MARK: - TCFv2 + /// The consent string for purposes consent as per TCFv2. public var purposeConsents: String? { set { UserConsentDataManager.shared.purposeConsents = newValue } get { UserConsentDataManager.shared.purposeConsents } } - /* - Purpose 1 - Store and/or access information on a device - */ + /// Purpose 1 - Store and/or access information on a device public func getDeviceAccessConsent() -> Bool? { UserConsentDataManager.shared.getDeviceAccessConsent() } + /// Returns whether the user has consented to access device data as an `NSNumber`. public func getDeviceAccessConsentObjc() -> NSNumber? { UserConsentDataManager.shared.getDeviceAccessConsent() as NSNumber? } + /// Returns the user's consent for a specific purpose by index. public func getPurposeConsent(index: Int) -> Bool? { UserConsentDataManager.shared.getPurposeConsent(index: index) } + /// Checks if access to device data is allowed. public func isAllowedAccessDeviceData() -> Bool { UserConsentDataManager.shared.isAllowedAccessDeviceData() } // MARK: - External User Ids + /// Array of external user IDs. + /// + /// This property holds the external user IDs associated with the user. public var externalUserIds = [ExternalUserId]() - /** - * This method allows to save External User Id in the User Defaults - */ + /// This method allows to save External User Id in the User Defaults public func storeExternalUserId(_ externalUserId: ExternalUserId) { if let index = externalUserIds.firstIndex(where: {$0.source == externalUserId.source}) { externalUserIds[index] = externalUserId @@ -217,16 +206,13 @@ public class Targeting: NSObject { StorageUtils.setExternalUserIds(value: externalUserIds) } - /** - * This method allows to get All External User Ids from User Defaults - */ + + /// This method allows to get All External User Ids from User Defaults public func fetchStoredExternalUserIds()->[ExternalUserId]? { return StorageUtils.getExternalUserIds() } - /** - * This method allows to get External User Id from User Defaults by passing respective 'source' string as param - */ + /// This method allows to get External User Id from User Defaults by passing respective 'source' string as param public func fetchStoredExternalUserId(_ source : String)->ExternalUserId? { guard let array = StorageUtils.getExternalUserIds(), let externalUserId = array.first(where: {$0.source == source}) else{ return nil @@ -234,9 +220,7 @@ public class Targeting: NSObject { return externalUserId } - /** - * This method allows to remove specific External User Id from User Defaults by passing respective 'source' string as param - */ + /// This method allows to remove specific External User Id from User Defaults by passing respective 'source' string as param public func removeStoredExternalUserId(_ source : String) { if let index = externalUserIds.firstIndex(where: {$0.source == source}) { externalUserIds.remove(at: index) @@ -244,9 +228,7 @@ public class Targeting: NSObject { } } - /** - * This method allows to remove all the External User Ids from User Defaults - */ + /// This method allows to remove all the External User Ids from User Defaults public func removeStoredExternalUserIds() { if var arrayExternalUserIds = StorageUtils.getExternalUserIds(){ arrayExternalUserIds.removeAll() @@ -275,62 +257,57 @@ public class Targeting: NSObject { // MARK: - Application Information - /** - This is the deep-link URL for the app screen that is displaying the ad. This can be an iOS universal link. - */ + /// This is the deep-link URL for the app screen that is displaying the ad. This can be an iOS universal link. public var contentUrl: String? - /** - App's publisher name. - */ + /// App's publisher name. public var publisherName: String? - /** - ID of publisher app in Apple’s App Store. - */ + /// ID of publisher app in Apple’s App Store. public var sourceapp: String? + /// App store URL for an installed app public var storeURL: String? { get { parameterDictionary[PBMParameterKeys.APP_STORE_URL.rawValue] } set { parameterDictionary[PBMParameterKeys.APP_STORE_URL.rawValue] = newValue } } + /// Domain name of the app public var domain: String? - /** - * The itunes app id for targeting - */ + /// The itunes app id for targeting public var itunesID: String? - /** - * The application location for targeting - */ + /// The application location for targeting public var location: CLLocation? - /** - * The application location precision for targeting - */ + /// The application location precision for targeting public var locationPrecision: Int? + /// Objective-C API public func setLocationPrecision(_ newValue: NSNumber?) { locationPrecision = newValue?.intValue } + /// Objective-C API public func getLocationPrecision() -> NSNumber? { return locationPrecision as NSNumber? } // MARK: - Location and connection information - /** - CLLocationCoordinate2D. - See CoreLocation framework documentation. - */ + /// CLLocationCoordinate2D. + /// See CoreLocation framework documentation. public var coordinate: NSValue? // MARK: - Public Methods + /// Adds a parameter to the parameter dictionary with a specified name. + /// + /// - Parameters: + /// - value: The value of the parameter. + /// - withName: The name of the parameter. If `nil`, the parameter is not added. public func addParam(_ value: String, withName: String?) { guard let name = withName else { Log.error("Invalid user parameter.") @@ -344,6 +321,9 @@ public class Targeting: NSObject { } } + /// Sets custom parameters by adding each key-value pair to the parameter dictionary. + /// + /// - Parameter params: A dictionary of parameters to set. If `nil`, no parameters are added. public func setCustomParams(_ params: [String : String]?) { guard let params = params else { return @@ -356,6 +336,11 @@ public class Targeting: NSObject { } } + /// Adds a custom parameter to the parameter dictionary with a prefixed name. + /// + /// - Parameters: + /// - value: The value of the custom parameter. + /// - withName: The name of the custom parameter. If `nil`, the parameter is not added. public func addCustomParam(_ value: String, withName: String?) { guard let name = withName else { return @@ -365,35 +350,53 @@ public class Targeting: NSObject { addParam(value, withName:prefixedName) } - // Store location in the user's section + /// Store location in the user's section public func setLatitude(_ latitude: Double, longitude: Double) { coordinate = NSValue(mkCoordinate: CLLocationCoordinate2DMake(latitude, longitude)) } // MARK: - Access Control List (ext.prebid.data) + /// Adds a bidder to the access control list. + /// + /// - Parameter bidderName: The name of the bidder to add. public func addBidderToAccessControlList(_ bidderName: String) { rawAccessControlList.insert(bidderName) } + /// Removes a bidder from the access control list. + /// + /// - Parameter bidderName: The name of the bidder to remove. public func removeBidderFromAccessControlList(_ bidderName: String) { rawAccessControlList.remove(bidderName) } + /// Clears all bidders from the access control list. public func clearAccessControlList() { rawAccessControlList.removeAll() } + /// Retrieves the current access control list. + /// + /// - Returns: An array of bidder names in the access control list. public func getAccessControlList() -> [String] { Array(rawAccessControlList) } + /// Access control list for external use. + /// + /// - Returns: An array of bidder names in the access control list. public var accessControlList: [String] { Array(rawAccessControlList) } // MARK: - Global User Data (user.ext.data) + /// Adds user data for a specified key. + /// + /// - Parameters: + /// - key: The key for the user data. + /// - value: The value to add for the specified key. public func addUserData(key: String, value: String) { var values = rawUserDataDictionary[key] ?? Set() values.insert(value) @@ -401,48 +404,77 @@ public class Targeting: NSObject { rawUserDataDictionary[key] = values } + /// Updates user data for a specified key with a new set of values. + /// + /// - Parameters: + /// - key: The key for the user data. + /// - value: The set of values to update for the specified key. public func updateUserData(key: String, value: Set) { rawUserDataDictionary[key] = value } + /// Removes user data for a specified key. + /// + /// - Parameter key: The key for the user data to remove. public func removeUserData(for key: String) { rawUserDataDictionary.removeValue(forKey: key) } + /// Clears all user data. public func clearUserData() { rawUserDataDictionary.removeAll() } + /// Retrieves all user data. + /// + /// - Returns: A dictionary mapping keys to arrays of values. public func getUserData() -> [String: [String]] { rawUserDataDictionary.mapValues { Array($0) } } + /// User data dictionary for external use. + /// + /// - Returns: A dictionary mapping keys to arrays of values. public var userDataDictionary: [String : [String]] { rawUserDataDictionary.mapValues { Array($0) } } // MARK: - Global User Keywords (user.keywords) + /// Adds a user keyword. + /// + /// - Parameter newElement: The keyword to add. public func addUserKeyword(_ newElement: String) { userKeywordsSet.insert(newElement) } + /// Adds multiple user keywords. + /// + /// - Parameter newElements: A set of keywords to add. public func addUserKeywords(_ newElements: Set) { userKeywordsSet.formUnion(newElements) } + /// Removes a user keyword. + /// + /// - Parameter element: The keyword to remove. public func removeUserKeyword(_ element: String) { userKeywordsSet.remove(element) } + /// Clears all user keywords. public func clearUserKeywords() { userKeywordsSet.removeAll() } + /// Retrieves all user keywords. + /// + /// - Returns: An array of user keywords. public func getUserKeywords() -> [String] { return Array(userKeywordsSet) } + /// Deprecated. Use `getUserKeywords` method instead. @available(*, deprecated, message: "This property is deprecated. Please, use getUserKeywords method instead.") public var userKeywords: [String] { Array(userKeywordsSet) @@ -450,36 +482,47 @@ public class Targeting: NSObject { // MARK: - Global Data (app.ext.data) + /// Deprecated. Use `addAppExtData` method instead. @available(*, deprecated, message: "This method is deprecated. Please, use addAppExtData method instead.") public func addContextData(key: String, value: String) { addAppExtData(key: key, value: value) } + /// Deprecated. Use `updateAppExtData` method instead. @available(*, deprecated, message: "This method is deprecated. Please, use updateAppExtData method instead.") public func updateContextData(key: String, value: Set) { updateAppExtData(key: key, value: value) } + /// Deprecated. Use `removeAppExtData` method instead. @available(*, deprecated, message: "This method is deprecated. Please, use removeAppExtData method instead.") public func removeContextData(for key: String) { removeAppExtData(for: key) } + /// Deprecated. Use `clearAppExtData` method instead. @available(*, deprecated, message: "This method is deprecated. Please, use clearAppExtData method instead.") public func clearContextData() { clearAppExtData() } + /// Deprecated. Use `getAppExtData` method instead. @available(*, deprecated, message: "This method is deprecated. Please, use getAppExtData method instead.") - public func getContextData() -> [String : [String]] { + public func getContextData() -> [String: [String]] { getAppExtData() } + /// Deprecated. Use `getAppExtData` method instead. @available(*, deprecated, message: "This property is deprecated. Please, use getAppExtData method instead.") - public var contextDataDictionary: [String : [String]] { + public var contextDataDictionary: [String: [String]] { getAppExtData() } + /// Adds application-specific data for a specified key. + /// + /// - Parameters: + /// - key: The key for the application data. + /// - value: The value to add for the specified key. public func addAppExtData(key: String, value: String) { var values = rawAppExtDataDictionary[key] ?? Set() values.insert(value) @@ -487,76 +530,108 @@ public class Targeting: NSObject { rawAppExtDataDictionary[key] = values } + /// Updates application-specific data for a specified key with a new set of values. + /// + /// - Parameters: + /// - key: The key for the application data. + /// - value: The set of values to update for the specified key. public func updateAppExtData(key: String, value: Set) { rawAppExtDataDictionary[key] = value } + /// Removes application-specific data for a specified key. + /// + /// - Parameter key: The key for the application data to remove. public func removeAppExtData(for key: String) { rawAppExtDataDictionary.removeValue(forKey: key) } + /// Clears all application-specific data. public func clearAppExtData() { rawAppExtDataDictionary.removeAll() } - public func getAppExtData() -> [String : [String]] { + /// Retrieves all application-specific data. + /// + /// - Returns: A dictionary mapping keys to arrays of values. + public func getAppExtData() -> [String: [String]] { rawAppExtDataDictionary.mapValues { Array($0) } } // MARK: - Global Keywords (app.keywords) + /// Deprecated. Use `addAppKeyword` method instead. @available(*, deprecated, message: "This method is deprecated. Please, use addAppKeyword method instead.") public func addContextKeyword(_ newElement: String) { addAppKeyword(newElement) } + /// Deprecated. Use `addAppKeywords` method instead. @available(*, deprecated, message: "This method is deprecated. Please, use addAppKeywords method instead.") public func addContextKeywords(_ newElements: Set) { addAppKeywords(newElements) } + /// Deprecated. Use `removeAppKeyword` method instead. @available(*, deprecated, message: "This method is deprecated. Please, use removeAppKeyword method instead.") public func removeContextKeyword(_ element: String) { removeAppKeyword(element) } + /// Deprecated. Use `clearAppKeywords` method instead. @available(*, deprecated, message: "This method is deprecated. Please, use clearAppKeywords method instead.") public func clearContextKeywords() { clearAppKeywords() } + /// Deprecated. Use `getAppKeywords` method instead. @available(*, deprecated, message: "This method is deprecated. Please, use getAppKeywords method instead.") public func getContextKeywords() -> [String] { getAppKeywords() } + /// Deprecated. Use `getAppKeywords` method instead. @available(*, deprecated, message: "This property is deprecated. Please, use getAppKeywords method instead.") public var contextKeywords: [String] { getAppKeywords() } + /// Adds an application keyword. + /// + /// - Parameter newElement: The keyword to add. public func addAppKeyword(_ newElement: String) { appKeywordsSet.insert(newElement) } + /// Adds multiple application keywords. + /// + /// - Parameter newElements: A set of keywords to add. public func addAppKeywords(_ newElements: Set) { appKeywordsSet.formUnion(newElements) } + /// Removes an application keyword. + /// + /// - Parameter element: The keyword to remove. public func removeAppKeyword(_ element: String) { appKeywordsSet.remove(element) } + /// Clears all application keywords. public func clearAppKeywords() { appKeywordsSet.removeAll() } + /// Retrieves all application keywords. + /// + /// - Returns: An array of application keywords. public func getAppKeywords() -> [String] { return Array(appKeywordsSet) } // MARK: - Internal Properties + /// Dictionary of parameters. public var parameterDictionary = [String : String]() private var userKeywordsSet = Set() diff --git a/PrebidMobile/ExternalUserId.swift b/PrebidMobile/ExternalUserId.swift index 7758dce86..01f8c5b8f 100644 --- a/PrebidMobile/ExternalUserId.swift +++ b/PrebidMobile/ExternalUserId.swift @@ -15,31 +15,37 @@ limitations under the License. import UIKit -/** - Defines the User Id Object from an External Thrid Party Source - */ +/// Defines the User Id Object from an External Thrid Party Source @objcMembers public class ExternalUserId: NSObject, NSCoding, NSSecureCoding, JSONConvertible { + /// Indicates whether the class supports secure coding. public static var supportsSecureCoding: Bool { true } // MARK: - Properties + + /// The source of the external user ID. public var source: String + + /// The identifier of the external user ID. public var identifier: String + + /// The type of the external user ID, represented as an optional `NSNumber`. public var atype: NSNumber? + + /// Additional attributes related to the external user ID, represented as an optional dictionary. public var ext: [String: Any]? // MARK: - Initialization - /** - Initialize ExternalUserId Class - - Parameter source: Source of the External User Id String. - - Parameter identifier: String of the External User Id. - - Parameter atype: (Optional) Int of the External User Id. - - Parameter ext: (Optional) Dictionary of the External User Id. - */ + + ///Initialize ExternalUserId Class + /// - Parameter source: Source of the External User Id String. + /// - Parameter identifier: String of the External User Id. + /// - Parameter atype: (Optional) Int of the External User Id. + /// - Parameter ext: (Optional) Dictionary of the External User Id. public init(source: String, identifier: String, atype: NSNumber? = nil, ext:[String: Any]? = nil) { self.source = source self.identifier = identifier @@ -48,6 +54,7 @@ public class ExternalUserId: NSObject, NSCoding, NSSecureCoding, JSONConvertible super.init() } + /// Encodes the properties of the class using the given encoder. public func encode(with coder: NSCoder) { coder.encode(self.source, forKey: "source") coder.encode(self.identifier, forKey: "identifier") @@ -55,6 +62,7 @@ public class ExternalUserId: NSObject, NSCoding, NSSecureCoding, JSONConvertible coder.encode(self.ext, forKey: "ext") } + /// Initializes an `ExternalUserId` instance from the given decoder. public required init?(coder: NSCoder) { self.source = coder.decodeObject(forKey: "source") as? String ?? "" self.identifier = coder.decodeObject(forKey: "identifier") as? String ?? "" @@ -62,6 +70,7 @@ public class ExternalUserId: NSObject, NSCoding, NSSecureCoding, JSONConvertible self.ext = coder.decodeObject(forKey: "ext") as? [String: Any] } + /// Converts the `ExternalUserId` instance to a JSON dictionary. public func toJSONDictionary() -> [AnyHashable: Any] { guard source.count != 0 && identifier.count != 0 else { return [:] diff --git a/PrebidMobile/Host.swift b/PrebidMobile/Host.swift index 06fb571bc..b6f1caaba 100644 --- a/PrebidMobile/Host.swift +++ b/PrebidMobile/Host.swift @@ -15,20 +15,19 @@ import UIKit +/// `PrebidHost` represents various Prebid server hosts used for ad bidding. @objc public enum PrebidHost: Int { - /** - URL [https://ib.adnxs.com/openrtb2/prebid](URL) - */ + /// URL [https://ib.adnxs.com/openrtb2/prebid](URL) case Appnexus - /** - URL [https://prebid-server.rubiconproject.com/openrtb2/auction](URL) - */ + /// URL [https://prebid-server.rubiconproject.com/openrtb2/auction](URL) case Rubicon + /// Custom Prebid server URL. The URL for this case should be set separately. case Custom + /// Returns the URL associated with the `PrebidHost` enum case. func name () -> String { switch self { case .Appnexus: return "https://ib.adnxs.com/openrtb2/prebid" @@ -38,24 +37,18 @@ import UIKit } } +/// A singleton class that manages the Prebid server URL, including a custom URL. @objcMembers public class Host: NSObject { private var customHostURL: URL? - /** - * The class is created as a singleton object & used - */ + /// The class is created as a singleton object & used public static let shared = Host() - override init() { + override init() {} - } - - /** - * The CustomHost property holds the URL for the custom prebid adaptor - */ - + /// The CustomHost property holds the URL for the custom prebid adaptor @objc public func setCustomHostURL(_ urlString: String?) throws { guard let url = URL.urlWithoutEncoding(from: urlString) else { throw ErrorCode.prebidServerURLInvalid(urlString ?? "") @@ -63,9 +56,7 @@ public class Host: NSObject { customHostURL = url } - /** - * This function retrieves the prebid server URL for the selected host - */ + /// This function retrieves the prebid server URL for the selected host public func getHostURL(host: PrebidHost) throws -> String { if (host == PrebidHost.Custom) { @@ -79,9 +70,7 @@ public class Host: NSObject { return host.name() } - /** - * This function verifies if the prebid server URL is in the url format - */ + /// This function verifies if the prebid server URL is in the url format public func verifyUrl (urlString: String?) -> Bool { //Check for nil if let urlString = urlString { @@ -94,11 +83,9 @@ public class Host: NSObject { } return false } - - /** - * This function used for unit testing to reset `customHostURL`. - * Internal only. - */ + + /// This function used for unit testing to reset `customHostURL`. + /// nternal only. func reset() { customHostURL = nil } diff --git a/PrebidMobile/PrebidMobileRendering/AdFormat.swift b/PrebidMobile/PrebidMobileRendering/AdFormat.swift index cd16486d4..15997bdf6 100644 --- a/PrebidMobile/PrebidMobileRendering/AdFormat.swift +++ b/PrebidMobile/PrebidMobileRendering/AdFormat.swift @@ -15,32 +15,50 @@ import Foundation +/// `AdFormat` is a class that represents different types of ad formats using an OptionSet. +/// The class also includes a deprecated display format for backward compatibility, marked with a deprecation message. @objcMembers public class AdFormat: NSObject, OptionSet { + /// The underlying type of the raw value. public typealias RawValue = Int + /// The raw integer value representing the ad format. public let rawValue: Int + /// The string representation of the ad format. public private(set) var stringEquivalent: String? + /// Initializes an `AdFormat` instance with a specified raw value and its string equivalent. + /// - Parameters: + /// - rawValue: The raw value representing the ad format. + /// - stringEquivalent: A string equivalent of the ad format. public convenience init(rawValue: RawValue, stringEquivalent: String) { self.init(rawValue: rawValue) self.stringEquivalent = stringEquivalent } + /// Initializes an `AdFormat` instance with a specified raw value. + /// - Parameter rawValue: The raw value representing the ad format. public required init(rawValue: RawValue) { self.rawValue = rawValue super.init() } - + + /// Represents a banner ad format. public static let banner = AdFormat(rawValue: 1 << 0, stringEquivalent: "banner") + + /// Represents a video ad format. public static let video = AdFormat(rawValue: 1 << 1, stringEquivalent: "video") + + /// Represents a native ad format. public static let native = AdFormat(rawValue: 1 << 2, stringEquivalent: "native") + /// Represents a deprecated display ad format. @available(*, deprecated, message: "Display ad format is deprecated. Please, use banner ad format instead.") public static let display = AdFormat(rawValue: 1 << 3, stringEquivalent: "banner") + /// An array containing all cases of ad formats, excluding deprecated ones. public static var allCases: [AdFormat] { [.banner, .video, .native] } diff --git a/PrebidMobile/PrebidMobileRendering/AdPosition.swift b/PrebidMobile/PrebidMobileRendering/AdPosition.swift index ad944ace6..a062c2fe1 100644 --- a/PrebidMobile/PrebidMobileRendering/AdPosition.swift +++ b/PrebidMobile/PrebidMobileRendering/AdPosition.swift @@ -15,25 +15,35 @@ import Foundation -//Ad position on screen. Refer to List 5.4: -//The following table specifies the position of the ad as a relative measure of visibility or prominence. This -//OpenRTB table has values derived from the Inventory Quality Guidelines (IQG). Practitioners should -//keep in sync with updates to the IQG values as published on IAB.com. Values “4” - “7” apply to apps per -//the mobile addendum to IQG version 2.1. -//Value Description -//0 Unknown -//1 Above the Fold -//2 DEPRECATED - May or may not be initially visible depending on screen size/resolution. -//3 Below the Fold -//4 Header -//5 Footer -//6 Sidebar -//7 Full Screen +/// Ad position on screen. Refer to List 5.4: +/// The following table specifies the position of the ad as a relative measure of visibility or prominence. This +/// OpenRTB table has values derived from the Inventory Quality Guidelines (IQG). Practitioners should +/// keep in sync with updates to the IQG values as published on IAB.com. Values “4” - “7” apply to apps per +/// the mobile addendum to IQG version 2.1. +/// Value Description +/// 0 Unknown +/// 1 Above the Fold +/// 2 DEPRECATED - May or may not be initially visible depending on screen size/resolution. +/// 3 Below the Fold +/// 4 Header +/// 5 Footer +/// 6 Sidebar +/// 7 Full Screen @objc(PBMAdPosition) public enum AdPosition: Int { - case undefined = 0 //0 Unknown - case header = 4 //4 Header - case footer = 5 //5 Footer - case sidebar = 6 //6 Sidebar - case fullScreen = 7 //7 Full Screen + + /// 0 Unknown + case undefined = 0 + + /// 4 Header + case header = 4 + + /// 5 Footer + case footer = 5 + + /// 6 Sidebar + case sidebar = 6 + + /// 7 Full Screen + case fullScreen = 7 } diff --git a/PrebidMobile/PrebidMobileRendering/AdTypes/AdView/Position.swift b/PrebidMobile/PrebidMobileRendering/AdTypes/AdView/Position.swift index 43d42af00..cd4a0fef6 100644 --- a/PrebidMobile/PrebidMobileRendering/AdTypes/AdView/Position.swift +++ b/PrebidMobile/PrebidMobileRendering/AdTypes/AdView/Position.swift @@ -15,6 +15,9 @@ import Foundation +/// Enum representing various positions on the screen. +/// +/// This enum defines positions that can be used for placing elements within an ad. The positions are typically used to determine where controls or components should be located within the ad's user interface. @objc(PBMPosition) public enum Position: Int { case undefined = -1 @@ -27,6 +30,10 @@ public enum Position: Int { case bottomRight case custom + /// Returns the corresponding `Position` enum value for a given string literal. + /// + /// - Parameter stringValue: A string representing the position. + /// - Returns: The `Position` enum value if it matches one of the predefined cases; otherwise, returns `nil`. public static func getPositionByStringLiteral(_ stringValue: String) -> Position? { switch stringValue { case "topleft": diff --git a/PrebidMobile/PrebidMobileRendering/AdTypes/AdView/VideoControlsConfiguration.swift b/PrebidMobile/PrebidMobileRendering/AdTypes/AdView/VideoControlsConfiguration.swift index 23194e4cb..fd80e5f2b 100644 --- a/PrebidMobile/PrebidMobileRendering/AdTypes/AdView/VideoControlsConfiguration.swift +++ b/PrebidMobile/PrebidMobileRendering/AdTypes/AdView/VideoControlsConfiguration.swift @@ -15,25 +15,22 @@ import Foundation +/// A class representing the configuration for video controls in an ad. +/// This includes properties for video duration, mute status, and button positioning and visibility. +/// Configuration values can be initialized from bid response or set directly by the user. @objc(PBMVideoControlsConfiguration) @objcMembers public class VideoControlsConfiguration: NSObject { - /** - This property indicates maximum video duration. - Obtained from the field ext,prebid.passthrough[].adConfiguration.maxvideoduration. - */ + /// This property indicates maximum video duration. + /// Obtained from the field ext,prebid.passthrough[].adConfiguration.maxvideoduration. private(set) public var maxVideoDuration: NSNumber? - /** - This property indicates whether the ad should run playback with sound or not. - Obtained from the field ext,prebid.passthrough[].adConfiguration.ismuted or set by user. - */ + /// This property indicates whether the ad should run playback with sound or not. + /// Obtained from the field ext,prebid.passthrough[].adConfiguration.ismuted or set by user. public var isMuted: Bool = false - /** - This property indicates the area which the close button should occupy on the screen. - Obtained from the field ext,prebid.passthrough[].adConfiguration.closebuttonarea or set by user. - */ + /// This property indicates the area which the close button should occupy on the screen. + /// Obtained from the field ext,prebid.passthrough[].adConfiguration.closebuttonarea or set by user. public var closeButtonArea: Double { set { if newValue <= 1 && newValue >= 0 { @@ -45,10 +42,8 @@ public class VideoControlsConfiguration: NSObject { get { _closeButtonArea } } - /** - This property indicates the position of the close button on the screen. - Obtained from the field ext,prebid.passthrough[].adConfiguration.closebuttonposition or set by user. - */ + /// This property indicates the position of the close button on the screen. + /// Obtained from the field ext,prebid.passthrough[].adConfiguration.closebuttonposition or set by user. public var closeButtonPosition: Position { set { if ![Position.topRight, Position.topLeft].contains(newValue) { @@ -61,10 +56,8 @@ public class VideoControlsConfiguration: NSObject { get { _closeButtonPosition } } - /** - This property indicates the area which the skip button should occupy on the screen. - Obtained from the field ext,prebid.passthrough[].adConfiguration.skipbuttonarea or set by user. - */ + /// This property indicates the area which the skip button should occupy on the screen. + /// Obtained from the field ext,prebid.passthrough[].adConfiguration.skipbuttonarea or set by user. public var skipButtonArea: Double { set { if newValue <= 1 && newValue >= 0 { @@ -77,10 +70,8 @@ public class VideoControlsConfiguration: NSObject { get { _skipButtonArea } } - /** - This property indicates the position of the skip button on the screen. - Obtained from the field ext,prebid.passthrough[].adConfiguration.skipbuttonposition or set by user. - */ + /// This property indicates the position of the skip button on the screen. + /// Obtained from the field ext,prebid.passthrough[].adConfiguration.skipbuttonposition or set by user. public var skipButtonPosition: Position { set { if ![Position.topRight, Position.topLeft].contains(newValue) { @@ -93,20 +84,14 @@ public class VideoControlsConfiguration: NSObject { get { _skipButtonPosition } } - /** - This property indicates the number of seconds which should be passed from the start of playback until the skip or close button should be shown. - Obtained from the field ext,prebid.passthrough[].adConfiguration.skipdelay or set by user. - */ + /// This property indicates the number of seconds which should be passed from the start of playback until the skip or close button should be shown. + /// Obtained from the field ext,prebid.passthrough[].adConfiguration.skipdelay or set by user. public var skipDelay = PBMConstants.SKIP_DELAY_DEFAULT.doubleValue - /** - This property indicates whether mute controls is visible on the screen. - */ + /// This property indicates whether mute controls is visible on the screen. public var isSoundButtonVisible = false - /** - Use to initialize video controls with server values. - */ + /// Use to initialize video controls with server values. public func initialize(with ortbAdConfiguration: PBMORTBAdConfiguration?) { guard let ortbAdConfiguration = ortbAdConfiguration else { diff --git a/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/GAM/BannerEventHandler.swift b/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/GAM/BannerEventHandler.swift index eccdb0a21..678220e88 100644 --- a/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/GAM/BannerEventHandler.swift +++ b/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/GAM/BannerEventHandler.swift @@ -16,6 +16,9 @@ import Foundation import UIKit +/// A protocol for handling events related to banner ads in the PBM SDK. +/// +/// This protocol defines methods and properties for managing events associated with banner ads, including loading events, user interactions, and ad sizes. Implementing this protocol allows for custom handling of these events within the PBM SDK. @objc public protocol BannerEventHandler : PBMPrimaryAdRequesterProtocol { /// Delegate for custom event handler to inform the PBM SDK about the events related to the ad server communication. diff --git a/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/GAM/BannerView.swift b/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/GAM/BannerView.swift index 5f4028764..d2db18d6d 100644 --- a/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/GAM/BannerView.swift +++ b/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/GAM/BannerView.swift @@ -17,48 +17,60 @@ import UIKit fileprivate let assertionMessageMainThread = "Expected to only be called on the main thread" +/// The view that will display the particular banner ad. Built for rendering type of integration. public class BannerView: UIView, BannerAdLoaderDelegate, AdLoadFlowControllerDelegate, BannerEventInteractionDelegate, DisplayViewInteractionDelegate { + /// The ad unit configuration. public let adUnitConfig: AdUnitConfig + + /// The event handler for banner view events. public let eventHandler: BannerEventHandler? // MARK: - Public Properties + /// Banner-specific parameters. @objc public var bannerParameters: BannerParameters { get { adUnitConfig.adConfiguration.bannerParameters } } + /// Video-specific parameters. @objc public var videoParameters: VideoParameters { get { adUnitConfig.adConfiguration.videoParameters } } + /// The last bid response received. @objc public var lastBidResponse: BidResponse? { adLoadFlowController?.bidResponse } + /// ID of Stored Impression on the Prebid server @objc public var configID: String { adUnitConfig.configId } + /// The interval for refreshing the ad. @objc public var refreshInterval: TimeInterval { get { adUnitConfig.refreshInterval } set { adUnitConfig.refreshInterval = newValue } } + /// Additional sizes for the ad. @objc public var additionalSizes: [CGSize]? { get { adUnitConfig.additionalSizes } set { adUnitConfig.additionalSizes = newValue } } + /// The ad format (e.g., banner, video). @objc public var adFormat: AdFormat { get { adUnitConfig.adFormats.first ?? .banner } set { adUnitConfig.adFormats = [newValue] } } + /// The position of the ad on the screen. @objc public var adPosition: AdPosition { get { adUnitConfig.adPosition } set { adUnitConfig.adPosition = newValue } @@ -69,6 +81,7 @@ public class BannerView: UIView, set { adUnitConfig.ortbConfig = newValue } } + /// ORTB configuration string. @objc public weak var delegate: BannerViewDelegate? /// Subscribe to plugin renderer events @@ -115,6 +128,12 @@ public class BannerView: UIView, // MARK: - Public Methods + /// Initializes a new `BannerView`. + /// - Parameters: + /// - frame: The frame rectangle for the view. + /// - configID: The configuration ID for the ad unit. + /// - adSize: The size of the ad. + /// - eventHandler: The event handler for the banner view. @objc public init(frame: CGRect, configID: String, adSize: CGSize, @@ -162,7 +181,10 @@ public class BannerView: UIView, }) } - + /// Convenience initializer for creating a `BannerView` with a configuration ID and event handler. + /// - Parameters: + /// - configID: The configuration ID for the ad unit. + /// - eventHandler: The event handler for the banner view. @objc public convenience init(configID: String, eventHandler: BannerEventHandler) { @@ -179,6 +201,11 @@ public class BannerView: UIView, } } + /// Convenience initializer for creating a `BannerView` with a frame, configuration ID, and ad size. + /// - Parameters: + /// - frame: The frame rectangle for the view. + /// - configID: The configuration ID for the ad unit. + /// - adSize: The size of the ad. @objc public convenience init(frame: CGRect, configID: String, adSize: CGSize) { @@ -196,14 +223,18 @@ public class BannerView: UIView, fatalError("init(coder:) has not been implemented") } + /// Loads the ad for the banner view. @objc public func loadAd() { adLoadFlowController?.refresh() } + /// Sets the stored auction response. + /// - Parameter storedAuction: The stored auction response string. @objc public func setStoredAuctionResponse(storedAuction:String){ Prebid.shared.storedAuctionResponse = storedAuction } + /// Stops the auto-refresh of the ad. @objc public func stopRefresh() { adLoadFlowController?.enqueueGatedBlock { [weak self] in self?.isRefreshStopped = true @@ -212,112 +243,162 @@ public class BannerView: UIView, // MARK: - Ext Data (imp[].ext.data) + /// Adds context data for a specified key. + /// - Parameters: + /// - data: The data to add. + /// - key: The key associated with the data. @available(*, deprecated, message: "This method is deprecated. Please, use addExtData method instead.") @objc public func addContextData(_ data: String, forKey key: String) { addExtData(key: key, value: data) } + /// Updates context data for a specified key. + /// - Parameters: + /// - data: A set of data to update. + /// - key: The key associated with the data. @available(*, deprecated, message: "This method is deprecated. Please, use updateExtData method instead.") @objc public func updateContextData(_ data: Set, forKey key: String) { updateExtData(key: key, value: data) } + /// Removes context data for a specified key. + /// - Parameter key: The key associated with the data to remove. @available(*, deprecated, message: "This method is deprecated. Please, use removeExtData method instead.") @objc public func removeContextDate(forKey key: String) { removeExtData(forKey: key) } + /// Clears all context data. @available(*, deprecated, message: "This method is deprecated. Please, use clearExtData method instead.") @objc public func clearContextData() { clearExtData() } + /// Adds ext data. + /// - Parameters: + /// - key: The key for the data. + /// - value: The value for the data. @objc public func addExtData(key: String, value: String) { adUnitConfig.addExtData(key: key, value: value) } + /// Updates ext data. + /// - Parameters: + /// - key: The key for the data. + /// - value: The value for the data. @objc public func updateExtData(key: String, value: Set) { adUnitConfig.updateExtData(key: key, value: value) } + /// Removes ext data. + /// - Parameters: + /// - key: The key for the data. @objc public func removeExtData(forKey: String) { adUnitConfig.removeExtData(for: forKey) } + /// Clears ext data. @objc public func clearExtData() { adUnitConfig.clearExtData() } // MARK: - Ext keywords (imp[].ext.keywords) + /// Adds a context keyword. + /// - Parameter newElement: The keyword to add. @available(*, deprecated, message: "This method is deprecated. Please, use addExtKeyword method instead.") @objc public func addContextKeyword(_ newElement: String) { addExtKeyword(newElement) } + /// Adds a set of context keywords. + /// - Parameter newElements: A set of keywords to add. @available(*, deprecated, message: "This method is deprecated. Please, use addExtKeywords method instead.") @objc public func addContextKeywords(_ newElements: Set) { addExtKeywords(newElements) } + /// Removes a context keyword. + /// - Parameter element: The keyword to remove. @available(*, deprecated, message: "This method is deprecated. Please, use removeExtKeyword method instead.") @objc public func removeContextKeyword(_ element: String) { removeExtKeyword(element) } + /// Clears all context keywords. @available(*, deprecated, message: "This method is deprecated. Please, use clearExtKeywords method instead.") @objc public func clearContextKeywords() { clearExtKeywords() } + /// Adds an extended keyword. + /// - Parameter newElement: The keyword to be added. @objc public func addExtKeyword(_ newElement: String) { adUnitConfig.addExtKeyword(newElement) } + /// Adds multiple extended keywords. + /// - Parameter newElements: A set of keywords to be added. @objc public func addExtKeywords(_ newElements: Set) { adUnitConfig.addExtKeywords(newElements) } + /// Removes an extended keyword. + /// - Parameter element: The keyword to be removed. @objc public func removeExtKeyword(_ element: String) { adUnitConfig.removeExtKeyword(element) } + /// Clears all extended keywords. @objc public func clearExtKeywords() { adUnitConfig.clearExtKeywords() } // MARK: - App Content (app.content.data) + /// Sets the app content data. + /// - Parameter appContent: The app content data. @objc public func setAppContent(_ appContent: PBMORTBAppContent) { adUnitConfig.setAppContent(appContent) } + /// Clears the app content data. @objc public func clearAppContent() { adUnitConfig.clearAppContent() } + /// Adds app content data objects. + /// - Parameter dataObjects: The data objects to be added. @objc public func addAppContentData(_ dataObjects: [PBMORTBContentData]) { adUnitConfig.addAppContentData(dataObjects) } - + + /// Removes an app content data object. + /// - Parameter dataObject: The data object to be removed. @objc public func removeAppContentDataObject(_ dataObject: PBMORTBContentData) { adUnitConfig.removeAppContentData(dataObject) } + /// Clears all app content data objects. @objc public func clearAppContentDataObjects() { adUnitConfig.clearAppContentData() } // MARK: - User Data (user.data) + /// Adds user data objects. + /// - Parameter userDataObjects: The user data objects to be added. @objc public func addUserData(_ userDataObjects: [PBMORTBContentData]) { adUnitConfig.addUserData(userDataObjects) } + /// Removes a user data object. + /// - Parameter userDataObject: The user data object to be removed. @objc public func removeUserData(_ userDataObject: PBMORTBContentData) { adUnitConfig.removeUserData(userDataObject) } + /// Clears all user data objects. @objc public func clearUserData() { adUnitConfig.clearUserData() } diff --git a/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/GAM/BannerViewDelegate.swift b/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/GAM/BannerViewDelegate.swift index 8d066020b..f5638ce60 100644 --- a/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/GAM/BannerViewDelegate.swift +++ b/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/GAM/BannerViewDelegate.swift @@ -16,48 +16,38 @@ import Foundation import UIKit + +/// A protocol for handling events related to banner ads in the PBM SDK. +/// +/// This protocol defines methods and properties for managing events associated with banner ads, including loading events, user interactions, and ad sizes. Implementing this protocol allows for custom handling of these events within the PBM SDK. @objc public protocol BannerViewDelegate: NSObjectProtocol { - /** @name Methods */ - /*! - @abstract Asks the delegate for a view controller instance to use for presenting modal views - as a result of user interaction on an ad. Usual implementation may simply return self, - if it is view controller class. - */ + /// Asks the delegate for a view controller instance to use for presenting modal views + /// as a result of user interaction on an ad. Usual implementation may simply return self, + /// if it is view controller class. func bannerViewPresentationController() -> UIViewController? - /*! - @abstract Notifies the delegate that an ad has been successfully loaded and rendered. - @param bannerView The BannerView instance sending the message. - */ + /// Notifies the delegate that an ad has been successfully loaded and rendered. + /// - Parameter bannerView: The BannerView instance sending the message. @objc optional func bannerView(_ bannerView: BannerView, didReceiveAdWithAdSize adSize: CGSize) - /*! - @abstract Notifies the delegate of an error encountered while loading or rendering an ad. - @param bannerView The BannerView instance sending the message. - @param error The error encountered while attempting to receive or render the - ad. - */ + /// Notifies the delegate of an error encountered while loading or rendering an ad. + /// - Parameter bannerView: The BannerView instance sending the message. + /// - Parameter error: The error encountered while attempting to receive or render the @objc optional func bannerView(_ bannerView: BannerView, didFailToReceiveAdWith error: Error) - /*! - @abstract Notifies the delegate whenever current app goes in the background due to user click. - @param bannerView The BannerView instance sending the message. - */ + /// Notifies the delegate whenever current app goes in the background due to user click. + /// - Parameter bannerView: The BannerView instance sending the message. @objc optional func bannerViewWillLeaveApplication(_ bannerView: BannerView) - /*! - @abstract Notifies delegate that the banner view will launch a modal - on top of the current view controller, as a result of user interaction. - @param bannerView The BannerView instance sending the message. - */ + /// Notifies delegate that the banner view will launch a modal + /// on top of the current view controller, as a result of user interaction. + /// - Parameter bannerView The BannerView instance sending the message. @objc optional func bannerViewWillPresentModal(_ bannerView: BannerView) - /*! - @abstract Notifies delegate that the banner view has dismissed the modal on top of - the current view controller. - @param bannerView The BannerView instance sending the message. - */ + /// Notifies delegate that the banner view has dismissed the modal on top of + /// the current view controller. + /// - Parameter bannerView: The BannerView instance sending the message. @objc optional func bannerViewDidDismissModal(_ bannerView: BannerView) } diff --git a/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/GAM/BaseInterstitialAdUnit.swift b/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/GAM/BaseInterstitialAdUnit.swift index 796d93ef1..3d4938b09 100644 --- a/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/GAM/BaseInterstitialAdUnit.swift +++ b/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/GAM/BaseInterstitialAdUnit.swift @@ -16,6 +16,7 @@ import Foundation import UIKit +/// A base class for interstitial ad units. public class BaseInterstitialAdUnit : NSObject, PBMInterstitialAdLoaderDelegate, @@ -26,32 +27,39 @@ public class BaseInterstitialAdUnit : // MARK: - Public Properties + /// The banner parameters used for configuring ad unit. @objc public var bannerParameters: BannerParameters { get { adUnitConfig.adConfiguration.bannerParameters } } + /// The video parameters used for configuring ad unit. @objc public var videoParameters: VideoParameters { get { adUnitConfig.adConfiguration.videoParameters } } + /// The last bid response received for the ad unit. @objc public var lastBidResponse: BidResponse? { return adLoadFlowController?.bidResponse } + /// The configuration ID for the ad unit. @objc public var configID: String { adUnitConfig.configId } + /// The set of ad formats supported by this ad unit. @objc public var adFormats: Set { get { adUnitConfig.adFormats } set { adUnitConfig.adFormats = newValue } } + /// The ORTB (OpenRTB) configuration string for the ad unit. @objc public var ortbConfig: String? { get { adUnitConfig.ortbConfig } set { adUnitConfig.ortbConfig = newValue } } + /// A Boolean value indicating whether the ad unit is ready to be displayed. @objc public var isReady: Bool { objc_sync_enter(blocksLockToken) if let block = isReadyBlock { @@ -64,28 +72,34 @@ public class BaseInterstitialAdUnit : return false } + /// A Boolean value indicating whether the video controls are muted. @objc public var isMuted: Bool { get { adUnitConfig.adConfiguration.videoControlsConfig.isMuted } set { adUnitConfig.adConfiguration.videoControlsConfig.isMuted = newValue } } + /// A Boolean value indicating whether the sound button is visible in the video controls. @objc public var isSoundButtonVisible: Bool { get { adUnitConfig.adConfiguration.videoControlsConfig.isSoundButtonVisible } set { adUnitConfig.adConfiguration.videoControlsConfig.isSoundButtonVisible = newValue } } + /// The area of the close button in the video controls as a percentage. @objc public var closeButtonArea: Double { get { adUnitConfig.adConfiguration.videoControlsConfig.closeButtonArea } set { adUnitConfig.adConfiguration.videoControlsConfig.closeButtonArea = newValue } } + /// The position of the close button in the video controls. @objc public var closeButtonPosition: Position { get { adUnitConfig.adConfiguration.videoControlsConfig.closeButtonPosition } set { adUnitConfig.adConfiguration.videoControlsConfig.closeButtonPosition = newValue } } + /// A delegate for handling interactions with the ad unit. @objc public weak var delegate: AnyObject? + /// The configuration object for the ad unit. public let adUnitConfig: AdUnitConfig // MARK: - Private Properties @@ -102,6 +116,11 @@ public class BaseInterstitialAdUnit : // MARK: - Public Methods + /// Initializes a new `BaseInterstitialAdUnit` with the specified configuration ID, minimum size percentage, and event handler. + /// - Parameters: + /// - configID: The unique identifier for the ad unit configuration. + /// - minSizePerc: The minimum size percentage for the ad unit. + /// - eventHandler: An optional event handler object for handling ad events. required public init(configID: String, minSizePerc: NSValue?, eventHandler: AnyObject?) { @@ -134,6 +153,11 @@ public class BaseInterstitialAdUnit : configValidationBlock: { _,_ in true } ) } + /// Initializes a new `BaseInterstitialAdUnit` with the specified configuration ID, minimum size percentage, and event handler. + /// - Parameters: + /// - configID: The unique identifier for the ad unit configuration. + /// - minSizePercentage: The minimum size percentage for the ad unit. + /// - eventHandler: An optional event handler object for handling ad events. public convenience init(configID: String, minSizePercentage: CGSize, eventHandler:AnyObject?) @@ -143,6 +167,10 @@ public class BaseInterstitialAdUnit : eventHandler: eventHandler) } + /// Initializes a new `BaseInterstitialAdUnit` with the specified configuration ID and event handler. + /// - Parameters: + /// - configID: The unique identifier for the ad unit configuration. + /// - eventHandler: An optional event handler object for handling ad events. public convenience init(configID: String, eventHandler:AnyObject?) { self.init(configID: configID, @@ -151,6 +179,10 @@ public class BaseInterstitialAdUnit : } + /// Initializes a new `BaseInterstitialAdUnit` with the specified configuration ID and minimum size percentage. + /// - Parameters: + /// - configID: The unique identifier for the ad unit configuration. + /// - minSizePercentage: The minimum size percentage for the ad unit. public convenience init(configID: String, minSizePercentage:CGSize) { @@ -159,6 +191,8 @@ public class BaseInterstitialAdUnit : eventHandler: nil) } + /// Initializes a new `BaseInterstitialAdUnit` with the specified configuration ID. + /// - Parameter configID: The unique identifier for the ad unit configuration. public convenience init(configID: String) { self.init(configID: configID, minSizePerc:nil, @@ -166,10 +200,14 @@ public class BaseInterstitialAdUnit : // MARK: - Public Methods + /// Loads a new ad. @objc public func loadAd() { adLoadFlowController.refresh() } + /// Shows the ad from a specified view controller. + /// - Parameter controller: The view controller from which the ad will be presented. + /// - Note: This method must be called on the main thread. @objc public func show(from controller: UIViewController) { // It is expected from the user to call this method on main thread assert(Thread.isMainThread, "Expected to only be called on the main thread"); @@ -194,118 +232,169 @@ public class BaseInterstitialAdUnit : // MARK: - Ext Data (imp[].ext.data) + /// Adds context data for a specified key. + /// - Parameters: + /// - data: The data to add. + /// - key: The key associated with the data. @available(*, deprecated, message: "This method is deprecated. Please, use addExtData method instead.") @objc public func addContextData(_ data: String, forKey key: String) { addExtData(key: key, value: data) } + /// Updates context data for a specified key. + /// - Parameters: + /// - data: A set of data to update. + /// - key: The key associated with the data. @available(*, deprecated, message: "This method is deprecated. Please, use updateExtData method instead.") @objc public func updateContextData(_ data: Set, forKey key: String) { updateExtData(key: key, value: data) } + /// Removes context data for a specified key. + /// - Parameter key: The key associated with the data to remove. @available(*, deprecated, message: "This method is deprecated. Please, use removeExtData method instead.") @objc public func removeContextDate(forKey key: String) { removeExtData(forKey: key) } + /// Clears all context data. @available(*, deprecated, message: "This method is deprecated. Please, use clearExtData method instead.") @objc public func clearContextData() { clearExtData() } + /// Adds ext data. + /// - Parameters: + /// - key: The key for the data. + /// - value: The value for the data. @objc public func addExtData(key: String, value: String) { adUnitConfig.addExtData(key: key, value: value) } + /// Updates ext data. + /// - Parameters: + /// - key: The key for the data. + /// - value: The value for the data. @objc public func updateExtData(key: String, value: Set) { adUnitConfig.updateExtData(key: key, value: value) } + /// Removes ext data. + /// - Parameters: + /// - key: The key for the data. @objc public func removeExtData(forKey: String) { adUnitConfig.removeExtData(for: forKey) } + /// Clears ext data. @objc public func clearExtData() { adUnitConfig.clearExtData() } // MARK: - Ext keywords (imp[].ext.keywords) + /// Adds a context keyword. + /// - Parameter newElement: The keyword to add. @available(*, deprecated, message: "This method is deprecated. Please, use addExtKeyword method instead.") @objc public func addContextKeyword(_ newElement: String) { addExtKeyword(newElement) } + /// Adds a set of context keywords. + /// - Parameter newElements: A set of keywords to add. @available(*, deprecated, message: "This method is deprecated. Please, use addExtKeywords method instead.") @objc public func addContextKeywords(_ newElements: Set) { addExtKeywords(newElements) } + /// Removes a context keyword. + /// - Parameter element: The keyword to remove. @available(*, deprecated, message: "This method is deprecated. Please, use removeExtKeyword method instead.") @objc public func removeContextKeyword(_ element: String) { removeExtKeyword(element) } + /// Clears all context keywords. @available(*, deprecated, message: "This method is deprecated. Please, use clearExtKeywords method instead.") @objc public func clearContextKeywords() { clearExtKeywords() } + /// Adds an extended keyword. + /// - Parameter newElement: The keyword to be added. @objc public func addExtKeyword(_ newElement: String) { adUnitConfig.addExtKeyword(newElement) } + /// Adds multiple extended keywords. + /// - Parameter newElements: A set of keywords to be added. @objc public func addExtKeywords(_ newElements: Set) { adUnitConfig.addExtKeywords(newElements) } + /// Removes an extended keyword. + /// - Parameter element: The keyword to be removed. @objc public func removeExtKeyword(_ element: String) { adUnitConfig.removeExtKeyword(element) } + /// Clears all extended keywords. @objc public func clearExtKeywords() { adUnitConfig.clearExtKeywords() } // MARK: - App Content (app.content.data) + /// Sets the app content data. + /// - Parameter appContent: The app content data. @objc public func setAppContent(_ appContent: PBMORTBAppContent) { adUnitConfig.setAppContent(appContent) } + /// Clears the app content data. @objc public func clearAppContent() { adUnitConfig.clearAppContent() } + /// Adds app content data objects. + /// - Parameter dataObjects: The data objects to be added. @objc public func addAppContentData(_ dataObjects: [PBMORTBContentData]) { adUnitConfig.addAppContentData(dataObjects) } - + + /// Removes an app content data object. + /// - Parameter dataObject: The data object to be removed. @objc public func removeAppContentDataObject(_ dataObject: PBMORTBContentData) { adUnitConfig.removeAppContentData(dataObject) } + /// Clears all app content data objects. @objc public func clearAppContentDataObjects() { adUnitConfig.clearAppContentData() } // MARK: - User Data (user.data) + /// Adds user data objects. + /// - Parameter userDataObjects: The user data objects to be added. @objc public func addUserData(_ userDataObjects: [PBMORTBContentData]) { adUnitConfig.addUserData(userDataObjects) } + /// Removes a user data object. + /// - Parameter userDataObject: The user data object to be removed. @objc public func removeUserData(_ userDataObject: PBMORTBContentData) { adUnitConfig.removeUserData(userDataObject) } + /// Clears all user data objects. @objc public func clearUserData() { adUnitConfig.clearUserData() } // MARK: - PBMInterstitialAdLoaderDelegate + /// Internal delegate method. public func interstitialAdLoader(_ interstitialAdLoader: PBMInterstitialAdLoader, loadedAd showBlock: @escaping (UIViewController?) -> Void, isReadyBlock: @escaping () -> Bool) { @@ -317,63 +406,76 @@ public class BaseInterstitialAdUnit : reportLoadingSuccess() } + /// Internal delegate method. public func interstitialAdLoader(_ interstitialAdLoader: PBMInterstitialAdLoader, createdInterstitialController interstitialController: InterstitialController) { interstitialController.interactionDelegate = self } + /// The event handler for the interstitial events. public var eventHandler: Any? // MARK: - AdLoadFlowControllerDelegate + /// Called when the ad load flow controller is about to send a bid request. public func adLoadFlowControllerWillSendBidRequest(_ adLoadFlowController: PBMAdLoadFlowController) { // nop } + /// Called when the ad load flow controller is about to request the primary ad. public func adLoadFlowControllerWillRequestPrimaryAd(_ adLoadFlowController: PBMAdLoadFlowController) { callEventHandler_setInteractionDelegate() } + /// Called to determine if the ad load flow controller should continue with the current flow. public func adLoadFlowControllerShouldContinue(_ adLoadFlowController: PBMAdLoadFlowController) -> Bool { true } + /// Called when the ad load flow controller fails with an error. public func adLoadFlowController(_ adLoadFlowController: PBMAdLoadFlowController, failedWithError error: Error?) { reportLoadingFailed(with: error) } // MARK: - InterstitialControllerInteractionDelegate + /// Tracks an impression for the given interstitial controller. public func trackImpression(forInterstitialController: InterstitialController) { DispatchQueue.main.async { self.callEventHandler_trackImpression() } } + /// Called when the ad in the interstitial controller is clicked. public func interstitialControllerDidClickAd(_ interstitialController: InterstitialController) { assert(Thread.isMainThread, "Expected to only be called on the main thread") callDelegate_didClickAd() } + /// Called when the ad in the interstitial controller is closed. public func interstitialControllerDidCloseAd(_ interstitialController: InterstitialController) { assert(Thread.isMainThread, "Expected to only be called on the main thread") callDelegate_didDismissAd() } + /// Called when the ad in the interstitial controller causes the app to leave. public func interstitialControllerDidLeaveApp(_ interstitialController: InterstitialController) { assert(Thread.isMainThread, "Expected to only be called on the main thread") callDelegate_willLeaveApplication() } + /// Called when the interstitial controller displays an ad. public func interstitialControllerDidDisplay(_ interstitialController: InterstitialController) { } + /// Called when the interstitial controller completes the ad display. public func interstitialControllerDidComplete(_ interstitialController: InterstitialController) { } + /// Provides the view controller to use for modal presentation. public func viewControllerForModalPresentation(fromInterstitialController: InterstitialController) -> UIViewController? { return targetController } @@ -394,12 +496,14 @@ public class BaseInterstitialAdUnit : // MARK: - InterstitialEventInteractionDelegate + /// Called when an ad is about to be presented. public func willPresentAd() { DispatchQueue.main.async { self.callDelegate_willPresentAd() } } + /// Called when an ad has been dismissed. public func didDismissAd() { objc_sync_enter(blocksLockToken) currentAdBlock = nil @@ -410,12 +514,14 @@ public class BaseInterstitialAdUnit : } } + /// Called when the ad causes the app to leave. public func willLeaveApp() { DispatchQueue.main.async { self.callDelegate_willLeaveApplication() } } + /// Called when an ad is clicked. public func didClickAd() { DispatchQueue.main.async { self.callDelegate_didClickAd() @@ -424,56 +530,69 @@ public class BaseInterstitialAdUnit : // MARK: - BaseInterstitialAdUnitProtocol + /// Requests an ad using the provided bid response. public func callEventHandler_requestAd(with bidResponse: BidResponse?) { } + /// Displays the ad using the provided view controller. public func callEventHandler_show(from controller: UIViewController?) { } // MARK: - Abstract Methods + /// Checks if the ad unit is ready to show an ad. public func callEventHandler_isReady() -> Bool { return false // to be overridden in subclass } + /// Notifies the delegate that an ad has been successfully received. public func callDelegate_didReceiveAd() { // to be overridden in subclass } + /// Notifies the delegate that the ad failed to load. public func callDelegate_didFailToReceiveAd(with: Error?) { // to be overridden in subclass } + /// Notifies the delegate that an ad is about to be presented. public func callDelegate_willPresentAd() { // to be overridden in subclass } + /// Notifies the delegate that an ad has been dismissed. public func callDelegate_didDismissAd() { // to be overridden in subclass } + /// Notifies the delegate that the app is about to leave due to an ad. public func callDelegate_willLeaveApplication() { // to be overridden in subclass } + /// Notifies the delegate that an ad has been clicked. public func callDelegate_didClickAd() { // to be overridden in subclass } + /// Sets the loading delegate for the event handler. public func callEventHandler_setLoadingDelegate(_ loadingDelegate: NSObject?) { // to be overridden in subclass } + /// Sets the interaction delegate for the event handler. public func callEventHandler_setInteractionDelegate() { // to be overridden in subclass } + /// Shows the ad from the provided view controller. public func callEventHandler_showFromViewController(controller: UIViewController?) { // to be overridden in subclass } + /// Tracks an impression for the ad. public func callEventHandler_trackImpression() { // to be overridden in subclass } diff --git a/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/GAM/InterstitialAdUnitDelegate.swift b/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/GAM/InterstitialAdUnitDelegate.swift index 33b9760ab..9842ce003 100644 --- a/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/GAM/InterstitialAdUnitDelegate.swift +++ b/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/GAM/InterstitialAdUnitDelegate.swift @@ -15,11 +15,10 @@ import Foundation -/*! - * Protocol for interaction with the InterstitialAdUnit . - * - * All messages will be invoked on the main thread. - */ + +/// Protocol for interaction with the InterstitialAdUnit . +/// +/// All messages will be invoked on the main thread. @objc public protocol InterstitialAdUnitDelegate: NSObjectProtocol { diff --git a/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/GAM/InterstitialRenderingAdUnit.swift b/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/GAM/InterstitialRenderingAdUnit.swift index 0190c1290..e0d9c5488 100644 --- a/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/GAM/InterstitialRenderingAdUnit.swift +++ b/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/GAM/InterstitialRenderingAdUnit.swift @@ -15,30 +15,39 @@ import UIKit +/// Represents an interstitial ad unit. Built for rendering type of integration. @objcMembers public class InterstitialRenderingAdUnit: BaseInterstitialAdUnit { + /// The area of the skip button in the video controls, specified as a percentage of the screen width. @objc public var skipButtonArea: Double { get { adUnitConfig.adConfiguration.videoControlsConfig.skipButtonArea } set { adUnitConfig.adConfiguration.videoControlsConfig.skipButtonArea = newValue } } + /// The position of the skip button in the video controls. @objc public var skipButtonPosition: Position { get { adUnitConfig.adConfiguration.videoControlsConfig.skipButtonPosition } set { adUnitConfig.adConfiguration.videoControlsConfig.skipButtonPosition = newValue } } + /// The delay before the skip button appears, in seconds. @objc public var skipDelay: Double { get { adUnitConfig.adConfiguration.videoControlsConfig.skipDelay } set { adUnitConfig.adConfiguration.videoControlsConfig.skipDelay = newValue } } + /// Initializes a new interstitial rendering ad unit with the specified configuration ID. + /// - Parameter configID: The unique identifier for the ad unit configuration. @objc public init(configID: String) { super.init(configID: configID, minSizePerc: nil, eventHandler: InterstitialEventHandlerStandalone()) } + /// Initializes a new interstitial rendering ad unit with the specified configuration ID and minimum size percentage. + /// - Parameter configID: The unique identifier for the ad unit configuration. + /// - Parameter minSizePercentage: The minimum size percentage of the ad. @objc public init(configID: String, minSizePercentage: CGSize) { super.init( configID: configID, @@ -46,6 +55,10 @@ public class InterstitialRenderingAdUnit: BaseInterstitialAdUnit { eventHandler: InterstitialEventHandlerStandalone()) } + /// Initializes a new interstitial rendering ad unit with the specified configuration ID, minimum size percentage, and event handler. + /// - Parameter configID: The unique identifier for the ad unit configuration. + /// - Parameter minSizePercentage: The minimum size percentage of the ad. + /// - Parameter eventHandler: The event handler to manage ad events. @objc public init(configID: String, minSizePercentage: CGSize, eventHandler: AnyObject) { super.init( configID: configID, @@ -53,6 +66,10 @@ public class InterstitialRenderingAdUnit: BaseInterstitialAdUnit { eventHandler: eventHandler) } + /// Initializes a new interstitial rendering ad unit with the specified configuration ID, minimum size percentage, and event handler. + /// - Parameter configID: The unique identifier for the ad unit configuration. + /// - Parameter minSizePerc: The minimum size percentage of the ad. + /// - Parameter eventHandler: The event handler to manage ad events. @objc required init(configID: String, minSizePerc: NSValue?, eventHandler: AnyObject?) { super.init( configID: configID, @@ -62,62 +79,74 @@ public class InterstitialRenderingAdUnit: BaseInterstitialAdUnit { // MARK: - Protected overrides + /// Called when an ad is successfully received. @objc public override func callDelegate_didReceiveAd() { if let delegate = self.delegate as? InterstitialAdUnitDelegate { delegate.interstitialDidReceiveAd?(self) } } + /// Called when the ad fails to be received. @objc public override func callDelegate_didFailToReceiveAd(with error: Error?) { if let delegate = self.delegate as? InterstitialAdUnitDelegate { delegate.interstitial?(self, didFailToReceiveAdWithError: error) } } + /// Called when the ad will be presented. @objc public override func callDelegate_willPresentAd() { if let delegate = self.delegate as? InterstitialAdUnitDelegate { delegate.interstitialWillPresentAd?(self) } } + /// Called when the ad is dismissed. @objc public override func callDelegate_didDismissAd() { if let delegate = self.delegate as? InterstitialAdUnitDelegate { delegate.interstitialDidDismissAd?(self) } } + /// Called when the user will leave the application. @objc public override func callDelegate_willLeaveApplication() { if let delegate = self.delegate as? InterstitialAdUnitDelegate { delegate.interstitialWillLeaveApplication?(self) } } + /// Called when the ad is clicked. @objc public override func callDelegate_didClickAd() { if let delegate = self.delegate as? InterstitialAdUnitDelegate { delegate.interstitialDidClickAd?(self) } } - + + /// Checks if the ad is ready to be displayed. @objc public override func callEventHandler_isReady() -> Bool { interstitialEventHandler?.isReady ?? false } - + + /// Sets the loading delegate for the event handler. @objc public override func callEventHandler_setLoadingDelegate(_ loadingDelegate: NSObject?) { interstitialEventHandler?.loadingDelegate = loadingDelegate as? RewardedEventLoadingDelegate } + /// Sets the interaction delegate for the event handler. @objc public override func callEventHandler_setInteractionDelegate() { interstitialEventHandler?.interactionDelegate = self } + /// Requests an ad with the specified bid response @objc public override func callEventHandler_requestAd(with bidResponse: BidResponse?) { interstitialEventHandler?.requestAd(with: bidResponse) } + /// Shows the ad from the specified view controller. @objc public override func callEventHandler_show(from controller: UIViewController?) { interstitialEventHandler?.show(from: controller) } + /// Tracks an impression for the ad. @objc public override func callEventHandler_trackImpression() { interstitialEventHandler?.trackImpression?() } diff --git a/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/GAM/RewardedAdUnit.swift b/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/GAM/RewardedAdUnit.swift index fb5ba25e0..6a2ab7afb 100644 --- a/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/GAM/RewardedAdUnit.swift +++ b/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/GAM/RewardedAdUnit.swift @@ -15,14 +15,20 @@ import UIKit +/// Represents an rewarded ad unit. Built for rendering type of integration. @objc public class RewardedAdUnit: BaseInterstitialAdUnit, RewardedEventInteractionDelegate { + /// The reward object for the ad unit. @objc public private(set) var reward: NSObject? // MARK: - Lifecycle + /// Initializes a `RewardedAdUnit` with the given configuration ID and event handler. + /// + /// - Parameter configID: The configuration ID for the ad unit. + /// - Parameter eventHandler: The event handler for the ad unit. @objc public convenience init(configID: String, eventHandler: AnyObject) { self.init( configID: configID, @@ -30,6 +36,9 @@ public class RewardedAdUnit: BaseInterstitialAdUnit, eventHandler: eventHandler) } + /// Initializes a `RewardedAdUnit` with the given configuration ID and a default event handler. + /// + /// - Parameter configID: The configuration ID for the ad unit. @objc public convenience init(configID: String) { self.init( configID: configID, @@ -37,6 +46,11 @@ public class RewardedAdUnit: BaseInterstitialAdUnit, eventHandler: RewardedEventHandlerStandalone()) } + /// Initializes a `RewardedAdUnit` with the given configuration ID, minimum size percentage, and event handler. + /// + /// - Parameter configID: The configuration ID for the ad unit. + /// - Parameter minSizePerc: The minimum size percentage for the ad unit. + /// - Parameter eventHandler: The event handler for the ad unit. @objc required init(configID:String, minSizePerc: NSValue?, eventHandler: AnyObject?) { super.init( configID: configID, @@ -48,6 +62,10 @@ public class RewardedAdUnit: BaseInterstitialAdUnit, } // MARK: - PBMRewardedEventDelegate + + /// Called when the user earns a reward. + /// + /// - Parameter reward: The reward object associated with the event. @objc public func userDidEarnReward(_ reward: NSObject?) { DispatchQueue.main.async(execute: { [weak self] in self?.reward = reward @@ -57,6 +75,9 @@ public class RewardedAdUnit: BaseInterstitialAdUnit, // MARK: - BaseInterstitialAdUnitProtocol protocol + /// Called when the interstitial ad is closed. + /// + /// - Parameter interstitialController: The controller managing the interstitial ad. @objc public override func interstitialControllerDidCloseAd(_ interstitialController: InterstitialController) { callDelegate_rewardedAdUserDidEarnReward() super.interstitialControllerDidCloseAd(interstitialController) @@ -64,42 +85,53 @@ public class RewardedAdUnit: BaseInterstitialAdUnit, // MARK: - Protected overrides + /// Called when the ad unit receives an ad. @objc public override func callDelegate_didReceiveAd() { if let delegate = self.delegate as? RewardedAdUnitDelegate { delegate.rewardedAdDidReceiveAd?(self) } } + /// Called when the ad unit fails to receive an ad. + /// + /// - Parameter error: The error describing the failure. @objc public override func callDelegate_didFailToReceiveAd(with error: Error?) { if let delegate = self.delegate as? RewardedAdUnitDelegate { delegate.rewardedAd?(self, didFailToReceiveAdWithError: error) } } + /// Called when the ad unit will present an ad. @objc public override func callDelegate_willPresentAd() { if let delegate = self.delegate as? RewardedAdUnitDelegate { delegate.rewardedAdWillPresentAd?(self) } } + /// Called when the ad unit dismisses an ad. @objc public override func callDelegate_didDismissAd() { if let delegate = self.delegate as? RewardedAdUnitDelegate { delegate.rewardedAdDidDismissAd?(self) } } + /// Called when the ad unit will leave the application. @objc public override func callDelegate_willLeaveApplication() { if let delegate = self.delegate as? RewardedAdUnitDelegate { delegate.rewardedAdWillLeaveApplication?(self) } } + /// Called when the ad unit is clicked. @objc public override func callDelegate_didClickAd() { if let delegate = self.delegate as? RewardedAdUnitDelegate { delegate.rewardedAdDidClickAd?(self) } } + /// Returns whether the event handler is ready. + /// + /// - Returns: A boolean indicating if the event handler is ready. @objc public override func callEventHandler_isReady() -> Bool { if let eventHandler = self.eventHandler as? RewardedEventHandlerProtocol { return eventHandler.isReady @@ -108,30 +140,41 @@ public class RewardedAdUnit: BaseInterstitialAdUnit, } } + /// Sets the loading delegate for the event handler. + /// + /// - Parameter loadingDelegate: The loading delegate to set. @objc public override func callEventHandler_setLoadingDelegate(_ loadingDelegate: NSObject?) { if let eventHandler = self.eventHandler as? RewardedEventHandlerProtocol { eventHandler.loadingDelegate = loadingDelegate as? RewardedEventLoadingDelegate } } + /// Sets the interaction delegate for the event handler. @objc public override func callEventHandler_setInteractionDelegate() { if let eventHandler = self.eventHandler as? RewardedEventHandlerProtocol { eventHandler.interactionDelegate = self } } + /// Requests an ad with the given bid response. + /// + /// - Parameter bidResponse: The bid response to use for the ad request. @objc public override func callEventHandler_requestAd(with bidResponse: BidResponse?) { if let eventHandler = self.eventHandler as? RewardedEventHandlerProtocol { eventHandler.requestAd(with: bidResponse) } } + /// Shows the ad from the specified view controller. + /// + /// - Parameter controller: The view controller from which to present the ad. @objc public override func callEventHandler_show(from controller: UIViewController?) { if let eventHandler = self.eventHandler as? RewardedEventHandlerProtocol { eventHandler.show(from: controller) } } + /// Tracks the impression for the ad. @objc public override func callEventHandler_trackImpression() { if let eventHandler = self.eventHandler as? RewardedEventHandlerProtocol { eventHandler.trackImpression?() @@ -140,6 +183,7 @@ public class RewardedAdUnit: BaseInterstitialAdUnit, // MARK: - Private helpers + /// Calls the delegate method to notify that the user has earned a reward. func callDelegate_rewardedAdUserDidEarnReward() { if let delegate = self.delegate as? RewardedAdUnitDelegate { delegate.rewardedAdUserDidEarnReward?(self) diff --git a/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/GAM/RewardedAdUnitDelegate.swift b/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/GAM/RewardedAdUnitDelegate.swift index f4dfdbdcf..247ed78f2 100644 --- a/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/GAM/RewardedAdUnitDelegate.swift +++ b/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/GAM/RewardedAdUnitDelegate.swift @@ -15,11 +15,8 @@ import Foundation -/*! - * Protocol for interaction with the PBMRewardedAdUnit . - * - * All messages will be invoked on the main thread. - */ +/// Protocol for interaction with the RewardedAdUnit +/// All messages will be invoked on the main thread. @objc public protocol RewardedAdUnitDelegate: NSObjectProtocol { /// Called when an ad is loaded and ready for display diff --git a/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/GAM/RewardedEventHandlerProtocol.swift b/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/GAM/RewardedEventHandlerProtocol.swift index 8699e7e0b..f44615211 100644 --- a/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/GAM/RewardedEventHandlerProtocol.swift +++ b/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/GAM/RewardedEventHandlerProtocol.swift @@ -15,7 +15,9 @@ import Foundation - +/// A protocol for handling events related to rewarded ads. +/// +/// This protocol extends `PBMInterstitialAd` and defines properties for delegates that handle events related to the ad server communication and user interactions with rewarded ads. Implementing this protocol allows for custom handling of these events within the rewarded ad lifecycle. @objc public protocol RewardedEventHandlerProtocol: PBMInterstitialAd { /// Delegate for custom event handler to inform the PBM SDK about the events related to the ad server communication. diff --git a/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/MediationAPI/MediationBannerAdUnit.swift b/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/MediationAPI/MediationBannerAdUnit.swift index ffe318625..8e6882482 100644 --- a/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/MediationAPI/MediationBannerAdUnit.swift +++ b/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/MediationAPI/MediationBannerAdUnit.swift @@ -16,6 +16,8 @@ import Foundation import UIKit +/// This class is responsible for making bid request and providing the winning bid and targeting keywords to mediating SDKs. +/// This class is a part of Mediation API. @objcMembers public class MediationBannerAdUnit : NSObject { @@ -34,42 +36,51 @@ public class MediationBannerAdUnit : NSObject { var adUnitConfig: AdUnitConfig + /// Property that performs certain utilty work for the `MediationBannerAdUnit` public let mediationDelegate: PrebidMediationDelegate // MARK: - Computed properties + /// The configuration ID for an ad unit public var configID: String { adUnitConfig.configId } + /// The ad format for the ad unit. public var adFormat: AdFormat { get { adUnitConfig.adFormats.first ?? .banner } set { adUnitConfig.adFormats = [newValue] } } + /// The position of the ad on the screen. public var adPosition: AdPosition { get { adUnitConfig.adPosition } set { adUnitConfig.adPosition = newValue } } + /// Parameters for configuring banner ads. public var bannerParameters: BannerParameters { get { adUnitConfig.adConfiguration.bannerParameters } } + /// Parameters for configuring video ads. public var videoParameters: VideoParameters { get { adUnitConfig.adConfiguration.videoParameters } } + /// The refresh interval for the ad. public var refreshInterval: TimeInterval { get { adUnitConfig.refreshInterval } set { adUnitConfig.refreshInterval = newValue } } + /// Additional sizes for the ad unit. public var additionalSizes: [CGSize]? { get { adUnitConfig.additionalSizes } set { adUnitConfig.additionalSizes = newValue } } + /// OpenRTB configuration public var ortbConfig: String? { get { adUnitConfig.ortbConfig } set { adUnitConfig.ortbConfig = newValue } @@ -77,118 +88,171 @@ public class MediationBannerAdUnit : NSObject { // MARK: - Ext Data (imp[].ext.data) + /// This method obtains the context data keyword & value for adunit context targeting + /// if the key already exists the value will be appended to the list. No duplicates will be added @available(*, deprecated, message: "This method is deprecated. Please, use addExtData method instead.") - public func addContextData(_ data: String, forKey key: String) { - addExtData(key: key, value: data) + public func addContextData(key: String, value: String) { + addExtData(key: key, value: value) } - + + /// This method obtains the context data keyword & values for adunit context targeting + /// the values if the key already exist will be replaced with the new set of values @available(*, deprecated, message: "This method is deprecated. Please, use updateExtData method instead.") - public func updateContextData(_ data: Set, forKey key: String) { - updateExtData(key: key, value: data) + public func updateContextData(key: String, value: Set) { + updateExtData(key: key, value: value) } + /// This method allows to remove specific context data keyword & values set from adunit context targeting @available(*, deprecated, message: "This method is deprecated. Please, use removeExtData method instead.") - public func removeContextDate(forKey key: String) { - removeExtData(forKey: key) + public func removeContextData(forKey: String) { + removeExtData(forKey: forKey) } + /// This method allows to remove all context data set from adunit context targeting @available(*, deprecated, message: "This method is deprecated. Please, use clearExtData method instead.") public func clearContextData() { clearExtData() } + /// This method obtains the ext data keyword & value for adunit targeting. + /// If the key already exists the value will be appended to the list. No duplicates will be added public func addExtData(key: String, value: String) { adUnitConfig.addExtData(key: key, value: value) } + /// This method obtains the ext data keyword & values for adunit targeting. + /// The values if the key already exist will be replaced with the new set of values public func updateExtData(key: String, value: Set) { adUnitConfig.updateExtData(key: key, value: value) } + /// This method allows to remove specific ext data keyword & values set from adunit targeting public func removeExtData(forKey: String) { adUnitConfig.removeExtData(for: forKey) } + /// This method allows to remove all ext data set from adunit targeting public func clearExtData() { adUnitConfig.clearExtData() } // MARK: - Ext keywords (imp[].ext.keywords) + /// This method obtains the context keyword for adunit context targeting + /// Inserts the given element in the set if it is not already present. @available(*, deprecated, message: "This method is deprecated. Please, use addExtKeyword method instead.") - @objc public func addContextKeyword(_ newElement: String) { + public func addContextKeyword(_ newElement: String) { addExtKeyword(newElement) } + /// This method obtains the context keyword set for adunit context targeting + /// Adds the elements of the given set to the set. @available(*, deprecated, message: "This method is deprecated. Please, use addExtKeywords method instead.") - @objc public func addContextKeywords(_ newElements: Set) { + public func addContextKeywords(_ newElements: Set) { addExtKeywords(newElements) } + /// This method allows to remove specific context keyword from adunit context targeting @available(*, deprecated, message: "This method is deprecated. Please, use removeExtKeyword method instead.") - @objc public func removeContextKeyword(_ element: String) { + public func removeContextKeyword(_ element: String) { removeExtKeyword(element) } - + + /// This method allows to remove all keywords from the set of adunit context targeting @available(*, deprecated, message: "This method is deprecated. Please, use clearExtKeywords method instead.") - @objc public func clearContextKeywords() { + public func clearContextKeywords() { clearExtKeywords() } + /// This method obtains the keyword for adunit targeting + /// Inserts the given element in the set if it is not already present. public func addExtKeyword(_ newElement: String) { adUnitConfig.addExtKeyword(newElement) } + /// This method obtains the keyword set for adunit targeting + /// Adds the elements of the given set to the set. public func addExtKeywords(_ newElements: Set) { adUnitConfig.addExtKeywords(newElements) } + /// This method allows to remove specific keyword from adunit targeting public func removeExtKeyword(_ element: String) { adUnitConfig.removeExtKeyword(element) } + /// This method allows to remove all keywords from the set of adunit targeting public func clearExtKeywords() { adUnitConfig.clearExtKeywords() } // MARK: - App Content (app.content.data) - public func setAppContent(_ appContent: PBMORTBAppContent) { - adUnitConfig.setAppContent(appContent) + /// Sets the app content object, replacing any existing content. + /// + /// - Parameter appContentObject: The `PBMORTBAppContent` object representing the app's content. + public func setAppContent(_ appContentObject: PBMORTBAppContent) { + adUnitConfig.setAppContent(appContentObject) + } + + /// Retrieves the current app content object. + /// + /// - Returns: The current `PBMORTBAppContent` object, or `nil` if no content is set. + public func getAppContent() -> PBMORTBAppContent? { + return adUnitConfig.getAppContent() } + /// Clears the current app content object. public func clearAppContent() { adUnitConfig.clearAppContent() } + /// Adds an array of content data objects to the app content. + /// + /// - Parameter dataObjects: An array of `PBMORTBContentData` objects to add. public func addAppContentData(_ dataObjects: [PBMORTBContentData]) { adUnitConfig.addAppContentData(dataObjects) } - public func removeAppContentDataObject(_ dataObject: PBMORTBContentData) { + /// Removes a specific content data object from the app content. + /// + /// - Parameter dataObject: The `PBMORTBContentData` object to remove. + public func removeAppContentData(_ dataObject: PBMORTBContentData) { adUnitConfig.removeAppContentData(dataObject) } - public func clearAppContentDataObjects() { + /// Clears all content data objects from the app content. + public func clearAppContentData() { adUnitConfig.clearAppContentData() } // MARK: - User Data (user.data) + /// Adds an array of user data objects. + /// + /// - Parameter userDataObjects: An array of `PBMORTBContentData` objects to add to the user data. public func addUserData(_ userDataObjects: [PBMORTBContentData]) { adUnitConfig.addUserData(userDataObjects) } + /// Removes a specific user data object. + /// + /// - Parameter userDataObject: The `PBMORTBContentData` object to remove from the user data. public func removeUserData(_ userDataObject: PBMORTBContentData) { adUnitConfig.removeUserData(userDataObject) } + /// Clears all user data. public func clearUserData() { adUnitConfig.clearUserData() } // MARK: - Public Methods + /// Initializes a new mediation banner ad unit with the specified configuration ID, size, and mediation delegate. + /// - Parameter configID: The unique identifier for the ad unit configuration. + /// - Parameter size: The size of the ad. + /// - Parameter mediationDelegate: The delegate for handling mediation. public init(configID: String, size: CGSize, mediationDelegate: PrebidMediationDelegate) { adUnitConfig = AdUnitConfig(configId: configID, size: size) adUnitConfig.adConfiguration.bannerParameters.api = PrebidConstants.supportedRenderingBannerAPISignals @@ -219,6 +283,8 @@ public class MediationBannerAdUnit : NSObject { }) } + /// Makes bid request and setups mediation parameters. + /// - Parameter completion: The completion handler to call when the demand fetch is complete. public func fetchDemand(completion: ((ResultCode)->Void)?) { fetchDemand(connection: PrebidServerConnection.shared, @@ -227,10 +293,14 @@ public class MediationBannerAdUnit : NSObject { completion: completion) } + /// Stops the auto-refresh for the ad unit. public func stopRefresh() { isRefreshStopped = true } + /// Handles the event when the ad object fails to load an ad. + /// - Parameter adObject: The ad object that failed to load the ad. + /// - Parameter error: The error that occurred during the ad load. public func adObjectDidFailToLoadAd(adObject: UIView, with error: Error) { if adObject === self.adView || adObject === self.lastAdView { diff --git a/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/MediationAPI/MediationBaseInterstitialAdUnit.swift b/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/MediationAPI/MediationBaseInterstitialAdUnit.swift index 0e153ec81..f67e23387 100644 --- a/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/MediationAPI/MediationBaseInterstitialAdUnit.swift +++ b/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/MediationAPI/MediationBaseInterstitialAdUnit.swift @@ -14,37 +14,45 @@  */ import Foundation +/// Base class for interstitial ads in Mediation API. @objcMembers public class MediationBaseInterstitialAdUnit : NSObject { + /// Parameters for configuring banner ads. public var bannerParameters: BannerParameters { get { adUnitConfig.adConfiguration.bannerParameters } } + /// Parameters for configuring video ads. public var videoParameters: VideoParameters { get { adUnitConfig.adConfiguration.videoParameters } } + /// Indicates whether the video ad is muted. public var isMuted: Bool { get { adUnitConfig.adConfiguration.videoControlsConfig.isMuted } set { adUnitConfig.adConfiguration.videoControlsConfig.isMuted = newValue } } + /// Indicates whether the sound button is visible in the video ad. public var isSoundButtonVisible: Bool { get { adUnitConfig.adConfiguration.videoControlsConfig.isSoundButtonVisible } set { adUnitConfig.adConfiguration.videoControlsConfig.isSoundButtonVisible = newValue } } - + + /// The area for the close button in the video ad. public var closeButtonArea: Double { get { adUnitConfig.adConfiguration.videoControlsConfig.closeButtonArea } set { adUnitConfig.adConfiguration.videoControlsConfig.closeButtonArea = newValue } } - + + /// The position of the close button in the video ad. public var closeButtonPosition: Position { get { adUnitConfig.adConfiguration.videoControlsConfig.closeButtonPosition } set { adUnitConfig.adConfiguration.videoControlsConfig.closeButtonPosition = newValue } } + /// OpenRTB configuration for the ad unit. public var ortbConfig: String? { get { adUnitConfig.ortbConfig } set { adUnitConfig.ortbConfig = newValue } @@ -52,6 +60,7 @@ public class MediationBaseInterstitialAdUnit : NSObject { let adUnitConfig: AdUnitConfig + /// The configuration ID for the ad unit. public var configId: String { adUnitConfig.configId } @@ -74,6 +83,9 @@ public class MediationBaseInterstitialAdUnit : NSObject { videoParameters.placement = .Interstitial } + /// Makes bid request and setups mediation parameters. + /// - Parameters: + /// - completion: A closure called with the result code indicating the outcome of the demand fetch. public func fetchDemand(completion: ((ResultCode)->Void)?) { fetchDemand(connection: PrebidServerConnection.shared, sdkConfiguration: Prebid.shared, @@ -83,112 +95,154 @@ public class MediationBaseInterstitialAdUnit : NSObject { // MARK: - Ext Data (imp[].ext.data) + /// This method obtains the context data keyword & value for adunit context targeting + /// if the key already exists the value will be appended to the list. No duplicates will be added @available(*, deprecated, message: "This method is deprecated. Please, use addExtData method instead.") - public func addContextData(_ data: String, forKey key: String) { - adUnitConfig.addExtData(key: key, value: data) + public func addContextData(key: String, value: String) { + addExtData(key: key, value: value) } - + + /// This method obtains the context data keyword & values for adunit context targeting + /// the values if the key already exist will be replaced with the new set of values @available(*, deprecated, message: "This method is deprecated. Please, use updateExtData method instead.") - public func updateContextData(_ data: Set, forKey key: String) { - adUnitConfig.updateExtData(key: key, value: data) + public func updateContextData(key: String, value: Set) { + updateExtData(key: key, value: value) } + /// This method allows to remove specific context data keyword & values set from adunit context targeting @available(*, deprecated, message: "This method is deprecated. Please, use removeExtData method instead.") - public func removeContextDate(forKey key: String) { - adUnitConfig.removeExtData(for: key) + public func removeContextData(forKey: String) { + removeExtData(forKey: forKey) } + /// This method allows to remove all context data set from adunit context targeting @available(*, deprecated, message: "This method is deprecated. Please, use clearExtData method instead.") public func clearContextData() { - adUnitConfig.clearExtData() + clearExtData() } + /// This method obtains the ext data keyword & value for adunit targeting. + /// If the key already exists the value will be appended to the list. No duplicates will be added public func addExtData(key: String, value: String) { adUnitConfig.addExtData(key: key, value: value) } + /// This method obtains the ext data keyword & values for adunit targeting. + /// The values if the key already exist will be replaced with the new set of values public func updateExtData(key: String, value: Set) { adUnitConfig.updateExtData(key: key, value: value) } + /// This method allows to remove specific ext data keyword & values set from adunit targeting public func removeExtData(forKey: String) { adUnitConfig.removeExtData(for: forKey) } + /// This method allows to remove all ext data set from adunit targeting public func clearExtData() { adUnitConfig.clearExtData() } // MARK: - Ext keywords (imp[].ext.keywords) + /// This method obtains the context keyword for adunit context targeting + /// Inserts the given element in the set if it is not already present. @available(*, deprecated, message: "This method is deprecated. Please, use addExtKeyword method instead.") - @objc public func addContextKeyword(_ newElement: String) { - adUnitConfig.addExtKeyword(newElement) + public func addContextKeyword(_ newElement: String) { + addExtKeyword(newElement) } + /// This method obtains the context keyword set for adunit context targeting + /// Adds the elements of the given set to the set. @available(*, deprecated, message: "This method is deprecated. Please, use addExtKeywords method instead.") - @objc public func addContextKeywords(_ newElements: Set) { - adUnitConfig.addExtKeywords(newElements) + public func addContextKeywords(_ newElements: Set) { + addExtKeywords(newElements) } + /// This method allows to remove specific context keyword from adunit context targeting @available(*, deprecated, message: "This method is deprecated. Please, use removeExtKeyword method instead.") - @objc public func removeContextKeyword(_ element: String) { - adUnitConfig.removeExtKeyword(element) + public func removeContextKeyword(_ element: String) { + removeExtKeyword(element) } - + + /// This method allows to remove all keywords from the set of adunit context targeting @available(*, deprecated, message: "This method is deprecated. Please, use clearExtKeywords method instead.") - @objc public func clearContextKeywords() { - adUnitConfig.clearExtKeywords() + public func clearContextKeywords() { + clearExtKeywords() } + /// This method obtains the keyword for adunit targeting + /// Inserts the given element in the set if it is not already present. public func addExtKeyword(_ newElement: String) { adUnitConfig.addExtKeyword(newElement) } + /// This method obtains the keyword set for adunit targeting + /// Adds the elements of the given set to the set. public func addExtKeywords(_ newElements: Set) { adUnitConfig.addExtKeywords(newElements) } + /// This method allows to remove specific keyword from adunit targeting public func removeExtKeyword(_ element: String) { adUnitConfig.removeExtKeyword(element) } + /// This method allows to remove all keywords from the set of adunit targeting public func clearExtKeywords() { adUnitConfig.clearExtKeywords() } // MARK: - App Content (app.content.data) - public func setAppContent(_ appContent: PBMORTBAppContent) { - adUnitConfig.setAppContent(appContent) + /// Sets the app content object, replacing any existing content. + /// + /// - Parameter appContentObject: The `PBMORTBAppContent` object representing the app's content. + public func setAppContent(_ appContentObject: PBMORTBAppContent) { + adUnitConfig.setAppContent(appContentObject) } + /// Clears the current app content object. public func clearAppContent() { adUnitConfig.clearAppContent() } + /// Adds an array of content data objects to the app content. + /// + /// - Parameter dataObjects: An array of `PBMORTBContentData` objects to add. public func addAppContentData(_ dataObjects: [PBMORTBContentData]) { adUnitConfig.addAppContentData(dataObjects) } - public func removeAppContentDataObject(_ dataObject: PBMORTBContentData) { + /// Removes a specific content data object from the app content. + /// + /// - Parameter dataObject: The `PBMORTBContentData` object to remove. + public func removeAppContentData(_ dataObject: PBMORTBContentData) { adUnitConfig.removeAppContentData(dataObject) } - public func clearAppContentDataObjects() { + /// Clears all content data objects from the app content. + public func clearAppContentData() { adUnitConfig.clearAppContentData() } // MARK: - User Data (user.data) + /// Adds an array of user data objects. + /// + /// - Parameter userDataObjects: An array of `PBMORTBContentData` objects to add to the user data. public func addUserData(_ userDataObjects: [PBMORTBContentData]) { adUnitConfig.addUserData(userDataObjects) } + /// Removes a specific user data object. + /// + /// - Parameter userDataObject: The `PBMORTBContentData` object to remove from the user data. public func removeUserData(_ userDataObject: PBMORTBContentData) { adUnitConfig.removeUserData(userDataObject) } + /// Clears all user data. public func clearUserData() { adUnitConfig.clearUserData() } diff --git a/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/MediationAPI/MediationInterstitialAdUnit.swift b/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/MediationAPI/MediationInterstitialAdUnit.swift index c27a2b75f..698ec72e4 100644 --- a/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/MediationAPI/MediationInterstitialAdUnit.swift +++ b/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/MediationAPI/MediationInterstitialAdUnit.swift @@ -16,31 +16,38 @@ import Foundation import UIKit +/// This class is responsible for making bid request and providing the winning bid and targeting keywords to mediating SDKs. +/// This class is a part of Mediation API. @objcMembers -public class MediationInterstitialAdUnit : MediationBaseInterstitialAdUnit { +public class MediationInterstitialAdUnit: MediationBaseInterstitialAdUnit { // MARK: - Public Properties + /// The ad format for the ad unit. public var adFormats: Set { get { adUnitConfig.adFormats } set { adUnitConfig.adFormats = newValue } } + /// Additional sizes for the ad unit. public var additionalSizes: [CGSize]? { get { adUnitConfig.additionalSizes } set { adUnitConfig.additionalSizes = newValue } } + /// The area for the skip button in the video ad. public var skipButtonArea: Double { get { adUnitConfig.adConfiguration.videoControlsConfig.skipButtonArea } set { adUnitConfig.adConfiguration.videoControlsConfig.skipButtonArea = newValue } } + /// The position of the skip button in the video ad. public var skipButtonPosition: Position { get { adUnitConfig.adConfiguration.videoControlsConfig.skipButtonPosition } set { adUnitConfig.adConfiguration.videoControlsConfig.skipButtonPosition = newValue } } + /// The delay before the skip button appears in the video ad. public var skipDelay: Double { get { adUnitConfig.adConfiguration.videoControlsConfig.skipDelay } set { adUnitConfig.adConfiguration.videoControlsConfig.skipDelay = newValue } @@ -48,10 +55,19 @@ public class MediationInterstitialAdUnit : MediationBaseInterstitialAdUnit { // MARK: - Public Methods + /// Convenience initializer for the mediation interstitial ad unit. + /// - Parameters: + /// - configId: The unique identifier for the ad unit configuration. + /// - mediationDelegate: The delegate for handling mediation. public override convenience init(configId: String, mediationDelegate: PrebidMediationDelegate) { self.init(configId: configId, minSizePercentage: nil, mediationDelegate: mediationDelegate) } + /// Initializes a new mediation interstitial ad unit with the specified configuration ID, minimum size percentage, and mediation delegate. + /// - Parameters: + /// - configId: The unique identifier for the ad unit configuration. + /// - minSizePercentage: The minimum size percentage for the ad. + /// - mediationDelegate: The delegate for handling mediation. public init(configId: String, minSizePercentage: CGSize?, mediationDelegate: PrebidMediationDelegate) { super.init(configId: configId, mediationDelegate: mediationDelegate) @@ -62,6 +78,7 @@ public class MediationInterstitialAdUnit : MediationBaseInterstitialAdUnit { // MARK: - Computed Properties + /// The configuration ID for the ad unit. public override var configId: String { adUnitConfig.configId } diff --git a/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/MediationAPI/MediationNativeAdUnit.swift b/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/MediationAPI/MediationNativeAdUnit.swift index 2ac556bc3..9fc8564a0 100644 --- a/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/MediationAPI/MediationNativeAdUnit.swift +++ b/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/MediationAPI/MediationNativeAdUnit.swift @@ -15,6 +15,8 @@ import Foundation +/// This class is responsible for making bid request and providing the winning bid and targeting keywords to mediating SDKs. +/// This class is a part of Mediation API. @objcMembers public class MediationNativeAdUnit : NSObject { @@ -23,178 +25,247 @@ public class MediationNativeAdUnit : NSObject { // MARK: - Public Properties + /// The native ad unit that makes native request. public var nativeAdUnit: NativeRequest var configID: String // MARK: - Public Methods + /// Initializes a new instance of the `MediationNativeAdUnit` with the specified configuration ID and mediation delegate. + /// - Parameters: + /// - configId: The configuration ID for the ad unit. + /// - mediationDelegate: The delegate for mediation-related tasks. public init(configId: String, mediationDelegate: PrebidMediationDelegate) { self.configID = configId self.mediationDelegate = mediationDelegate self.nativeAdUnit = NativeRequest(configId: configId) } + /// Adds event trackers to the native ad unit. + /// - Parameter eventTrackers: An array of `NativeEventTracker` objects to add. public func addEventTracker(_ eventTrackers: [NativeEventTracker]) { nativeAdUnit.addNativeEventTracker(eventTrackers) } + /// Adds native assets to the native ad unit. + /// - Parameter assets: An array of `NativeAsset` objects to add. public func addNativeAssets(_ assets: [NativeAsset]) { nativeAdUnit.addNativeAssets(assets) } + /// Sets the context type for the native ad unit. + /// - Parameter contextType: The context type to set. public func setContextType(_ contextType: ContextType) { nativeAdUnit.context = contextType } + /// Sets the placement type for the native ad unit. + /// - Parameter placementType: The placement type to set. public func setPlacementType(_ placementType: PlacementType) { nativeAdUnit.placementType = placementType } + /// Sets the placement count for the native ad unit. + /// - Parameter placementCount: The placement count to set. public func setPlacementCount(_ placementCount: Int) { nativeAdUnit.placementCount = placementCount } + /// Sets the context subtype for the native ad unit. + /// - Parameter contextSubType: The context subtype to set. public func setContextSubType(_ contextSubType: ContextSubType) { nativeAdUnit.contextSubType = contextSubType } + /// Sets the sequence for the native ad unit. + /// - Parameter sequence: The sequence to set. public func setSequence(_ sequence: Int) { nativeAdUnit.sequence = sequence } + /// Sets the asset URL support for the native ad unit. + /// - Parameter assetURLSupport: The asset URL support value to set. public func setAssetURLSupport(_ assetURLSupport: Int) { nativeAdUnit.asseturlsupport = assetURLSupport } + /// Sets the DURL support for the native ad unit. + /// - Parameter dURLSupport: The DURL support value to set. public func setDURLSupport(_ dURLSupport: Int) { nativeAdUnit.durlsupport = dURLSupport } + /// Sets the privacy value for the native ad unit. + /// - Parameter privacy: The privacy value to set. public func setPrivacy(_ privacy: Int) { nativeAdUnit.privacy = privacy } + /// Sets the extended data for the native ad unit. + /// - Parameter ext: A dictionary containing the extended data to set. public func setExt(_ ext: [String: Any]) { nativeAdUnit.ext = ext } + /// Retrieves the OpenRTB configuration for the native ad unit. + /// - Returns: The OpenRTB configuration as a string, or `nil` if not set. public func getOrtbConfig() -> String? { return nativeAdUnit.getOrtbConfig() } + /// Sets the OpenRTB configuration for the native ad unit. + /// - Parameter ortbConfig: The OpenRTB configuration to set. public func setOrtbConfig(_ ortbConfig: String?) { nativeAdUnit.setOrtbConfig(ortbConfig) } // MARK: - App Content (app.content.data) + /// Sets the app content object, replacing any existing content. + /// - Parameter appContent: The `PBMORTBAppContent` object representing the app's content. public func setAppContent(_ appContent: PBMORTBAppContent) { nativeAdUnit.setAppContent(appContent) } + /// Clears the current app content object. public func clearAppContent() { nativeAdUnit.clearAppContent() } + /// Adds an array of content data objects to the app content. + /// - Parameter dataObjects: An array of `PBMORTBContentData` objects to add. public func addAppContentData(_ dataObjects: [PBMORTBContentData]) { nativeAdUnit.addAppContentData(dataObjects) } + /// Removes a specific content data object from the app content. + /// - Parameter dataObject: The `PBMORTBContentData` object to remove. public func removeAppContent(_ dataObject: PBMORTBContentData) { nativeAdUnit.removeAppContentData(dataObject) } // MARK: - User Data (user.data) + /// Adds an array of user data objects. + /// - Parameter userDataObjects: An array of `PBMORTBContentData` objects to add to the user data. public func addUserData(_ userDataObjects: [PBMORTBContentData]) { nativeAdUnit.addUserData(userDataObjects) } + /// Removes a specific user data object. + /// - Parameter userDataObject: The `PBMORTBContentData` object to remove from the user data. public func removeUserData(_ userDataObject: PBMORTBContentData) { nativeAdUnit.removeUserData(userDataObject) } + /// Clears all user data. public func clearUserData() { nativeAdUnit.clearUserData() } // MARK: - Ext Data (imp[].ext.data) + /// This method obtains the context data keyword & value for adunit context targeting + /// if the key already exists the value will be appended to the list. No duplicates will be added @available(*, deprecated, message: "This method is deprecated. Please, use addExtData method instead.") - public func addContextData(_ data: String, forKey key: String) { - addExtData(key: key, value: data) + public func addContextData(key: String, value: String) { + addExtData(key: key, value: value) } - + + /// This method obtains the context data keyword & values for adunit context targeting + /// the values if the key already exist will be replaced with the new set of values @available(*, deprecated, message: "This method is deprecated. Please, use updateExtData method instead.") - public func updateContextData(_ data: Set, forKey key: String) { - updateExtData(key: key, value: data) + public func updateContextData(key: String, value: Set) { + updateExtData(key: key, value: value) } + /// This method allows to remove specific context data keyword & values set from adunit context targeting @available(*, deprecated, message: "This method is deprecated. Please, use removeExtData method instead.") - public func removeContextDate(forKey key: String) { - removeExtData(forKey: key) + public func removeContextData(forKey: String) { + removeExtData(forKey: forKey) } + /// This method allows to remove all context data set from adunit context targeting @available(*, deprecated, message: "This method is deprecated. Please, use clearExtData method instead.") public func clearContextData() { clearExtData() } + /// This method obtains the ext data keyword & value for adunit targeting. + /// If the key already exists the value will be appended to the list. No duplicates will be added public func addExtData(key: String, value: String) { nativeAdUnit.addExtData(key: key, value: value) } + /// This method obtains the ext data keyword & values for adunit targeting. + /// The values if the key already exist will be replaced with the new set of values public func updateExtData(key: String, value: Set) { nativeAdUnit.updateExtData(key: key, value: value) } + /// This method allows to remove specific ext data keyword & values set from adunit targeting public func removeExtData(forKey: String) { nativeAdUnit.removeExtData(forKey: forKey) } + /// This method allows to remove all ext data set from adunit targeting public func clearExtData() { nativeAdUnit.clearExtData() } // MARK: - Ext keywords (imp[].ext.keywords) + /// This method obtains the context keyword for adunit context targeting + /// Inserts the given element in the set if it is not already present. @available(*, deprecated, message: "This method is deprecated. Please, use addExtKeyword method instead.") - @objc public func addContextKeyword(_ newElement: String) { + public func addContextKeyword(_ newElement: String) { addExtKeyword(newElement) } + /// This method obtains the context keyword set for adunit context targeting + /// Adds the elements of the given set to the set. @available(*, deprecated, message: "This method is deprecated. Please, use addExtKeywords method instead.") - @objc public func addContextKeywords(_ newElements: Set) { + public func addContextKeywords(_ newElements: Set) { addExtKeywords(newElements) } + /// This method allows to remove specific context keyword from adunit context targeting @available(*, deprecated, message: "This method is deprecated. Please, use removeExtKeyword method instead.") - @objc public func removeContextKeyword(_ element: String) { + public func removeContextKeyword(_ element: String) { removeExtKeyword(element) } - + + /// This method allows to remove all keywords from the set of adunit context targeting @available(*, deprecated, message: "This method is deprecated. Please, use clearExtKeywords method instead.") - @objc public func clearContextKeywords() { + public func clearContextKeywords() { clearExtKeywords() } + /// This method obtains the keyword for adunit targeting + /// Inserts the given element in the set if it is not already present. public func addExtKeyword(_ newElement: String) { nativeAdUnit.addExtKeyword(newElement) } + /// This method obtains the keyword set for adunit targeting + /// Adds the elements of the given set to the set. public func addExtKeywords(_ newElements: Set) { nativeAdUnit.addExtKeywords(newElements) } + /// This method allows to remove specific keyword from adunit targeting public func removeExtKeyword(_ element: String) { nativeAdUnit.removeExtKeyword(element) } + /// This method allows to remove all keywords from the set of adunit targeting public func clearExtKeywords() { nativeAdUnit.clearExtKeywords() } + /// Makes bid request for the native ad unit and setups mediation parameters. + /// - Parameter completion: The completion handler to call with the result code. public func fetchDemand(completion: ((ResultCode)->Void)?) { self.completion = completion diff --git a/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/MediationAPI/MediationRewardedAdUnit.swift b/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/MediationAPI/MediationRewardedAdUnit.swift index 694fa3966..3b8179710 100644 --- a/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/MediationAPI/MediationRewardedAdUnit.swift +++ b/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/MediationAPI/MediationRewardedAdUnit.swift @@ -15,11 +15,17 @@ import Foundation +/// This class is responsible for making bid request and providing the winning bid and targeting keywords to mediating SDKs. +/// This class is a part of Mediation API. @objcMembers public class MediationRewardedAdUnit : MediationBaseInterstitialAdUnit { // - MARK: Public Methods + /// Initializes a new instance of the `MediationRewardedAdUnit` with the specified configuration ID and mediation delegate. + /// - Parameters: + /// - configId: The configuration ID for the ad unit. + /// - mediationDelegate: The delegate for mediation-related tasks. public override init(configId: String, mediationDelegate: PrebidMediationDelegate) { super.init(configId: configId, mediationDelegate: mediationDelegate) diff --git a/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/MediationAPI/PrebidMediationDelegate.swift b/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/MediationAPI/PrebidMediationDelegate.swift index f020169d6..df8f8e81f 100644 --- a/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/MediationAPI/PrebidMediationDelegate.swift +++ b/PrebidMobile/PrebidMobileRendering/Prebid/Integrations/MediationAPI/PrebidMediationDelegate.swift @@ -16,24 +16,20 @@ import Foundation import UIKit -// This protocol is dedicated to manage the work with Mediation SDKs. +/// This protocol is dedicated to manage the work with Mediation SDKs. @objc public protocol PrebidMediationDelegate { - /** - Puts to ad object's localExtra the ad object (winning bid or native ad) and configId - and populates adObject's keywords by targeting info - @return YES on success and NO otherwise (when the passed ad has wrong type) - */ + /// Puts to ad object's localExtra the ad object (winning bid or native ad) and configId + /// and populates adObject's keywords by targeting info + /// @return YES on success and NO otherwise (when the passed ad has wrong type) func setUpAdObject(with values: [String: Any]) -> Bool - /** - Removes an bid info from ad object's localExtra - and prebid-specific keywords from ad object's keywords - */ + + /// Removes an bid info from ad object's localExtra + /// and prebid-specific keywords from ad object's keywords func cleanUpAdObject() - /** - Returns ad view that was passed into PrebidMediationDelegate earlier. - Returns nil if there was no view passed. - */ + + /// Returns ad view that was passed into PrebidMediationDelegate earlier. + /// Returns nil if there was no view passed. func getAdView() -> UIView? } diff --git a/PrebidMobile/ResultCode.swift b/PrebidMobile/ResultCode.swift index d8c219132..401fde43b 100644 --- a/PrebidMobile/ResultCode.swift +++ b/PrebidMobile/ResultCode.swift @@ -15,33 +15,68 @@ import Foundation +/// Enum representing the result codes for various operations within the Prebid SDK. +/// +/// This enum provides a range of result codes indicating different outcomes or errors that may occur during SDK operations. Each case corresponds to a specific result or error, which helps in diagnosing issues and understanding the status of SDK operations. @objc public enum ResultCode : Int { + + /// The demand fetch request was successful. case prebidDemandFetchSuccess = 0 + + /// The Prebid server was not specified in the request. case prebidServerNotSpecified + + /// The account ID provided is not recognized by the Prebid server. case prebidInvalidAccountId + + /// The config ID provided is not recognized by the Prebid server. case prebidInvalidConfigId + + /// The size requested is not recognized by the Prebid server. case prebidInvalidSize + + /// There was a network error during the operation. case prebidNetworkError + + /// The Prebid server encountered an error while processing the request. case prebidServerError + + /// The Prebid server did not return any bids. case prebidDemandNoBids + + /// The demand request timed out. case prebidDemandTimedOut + + /// The URL of the Prebid server is invalid. case prebidServerURLInvalid + + /// An unknown error occurred within the Prebid SDK. case prebidUnknownError + /// The structure of the response received is invalid. case prebidInvalidResponseStructure = 1000 + /// An internal error occurred within the SDK. case prebidInternalSDKError = 7000 + + /// Incorrect arguments were provided to the SDK. case prebidWrongArguments + + /// No VAST tag was found in the media data. case prebidNoVastTagInMediaData + /// Misuse of the SDK was detected. case prebidSDKMisuse = 8000 + + /// SDK misuse due to a previous fetch operation not being completed yet. case prebidSDKMisusePreviousFetchNotCompletedYet + /// The Prebid request does not contain any parameters. case prebidInvalidRequest - public func name () -> String { + /// Returns a descriptive name for the result code. + public func name() -> String { switch self { - case .prebidDemandFetchSuccess: return "Prebid demand fetch successful" case .prebidServerNotSpecified: diff --git a/README.md b/README.md index cf2661e61..0f36aa6f5 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,3 @@ -[![Build Status](https://api.travis-ci.org/prebid/prebid-mobile-ios.svg?branch=master)](https://travis-ci.org/prebid/prebid-mobile-ios) - # Prebid Mobile iOS SDK To work with Prebid Mobile, you will need accesss to a Prebid Server. See [this page](https://docs.prebid.org/prebid-server/overview/prebid-server-overview.html) for options. diff --git a/README_API_DOC.md b/README_API_DOC.md new file mode 100644 index 000000000..fb83748d7 --- /dev/null +++ b/README_API_DOC.md @@ -0,0 +1,9 @@ +# Prebid Mobile SDK - iOS API Reference + +Prebid iOS SDK is an open-source monetization library that allows you to integrate header bidding demand partners into the mobile app in various ways. The integration documentation can be found [here](https://docs.prebid.org/prebid-mobile/prebid-mobile.html). + +This section is autogenerated documentation describing the SDK's public classes, methods, and other code structures. It doesn't provide any integration guides but always provides updated API references. + +The documentation is generated for each SDK release. + +If you see any inconsistency or want to improve the process, you are always welcome to contribute to [Prebid Mobile iOS SDK](https://github.com/prebid/prebid-mobile-ios) on GitHub. diff --git a/scripts/testPrebidMobile.sh b/scripts/testPrebidMobile.sh index e20c8e954..fb4f7ebf3 100755 --- a/scripts/testPrebidMobile.sh +++ b/scripts/testPrebidMobile.sh @@ -32,6 +32,10 @@ pod install --repo-update echo -e "\n\n${GREEN}TEST PREBID MOBILE${NC}\n\n" +echo -e "\n${GREEN}Clean build\n" + +xcodebuild clean build + if [ "$run_only_with_latest_ios" != "YES" ] then echo -e "\n${GREEN}Running some unit tests for iOS 13${NC} \n" @@ -57,6 +61,8 @@ xcodebuild test \ -scheme "PrebidMobileTests" \ -destination 'platform=iOS Simulator,name=iPhone 15 Pro,OS=latest' | xcpretty --color --test + + if [[ ${PIPESTATUS[0]} == 0 ]]; then echo "✅ PrebidMobile Unit Tests Passed" else