{"id":18687905,"url":"https://github.com/tenmax/ad-placement-library-sdk-ios","last_synced_at":"2025-11-08T02:30:40.330Z","repository":{"id":254043619,"uuid":"844994990","full_name":"tenmax/ad-placement-library-sdk-ios","owner":"tenmax","description":null,"archived":false,"fork":false,"pushed_at":"2025-02-12T04:54:35.000Z","size":411,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-02-12T05:38:51.375Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tenmax.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-20T11:28:26.000Z","updated_at":"2025-02-12T04:54:06.000Z","dependencies_parsed_at":"2024-09-11T20:25:06.644Z","dependency_job_id":"92482f7b-250f-4645-99c2-2bd6d3973183","html_url":"https://github.com/tenmax/ad-placement-library-sdk-ios","commit_stats":null,"previous_names":["tenmax/ad-placement-library-sdk-ios"],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tenmax%2Fad-placement-library-sdk-ios","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tenmax%2Fad-placement-library-sdk-ios/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tenmax%2Fad-placement-library-sdk-ios/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tenmax%2Fad-placement-library-sdk-ios/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tenmax","download_url":"https://codeload.github.com/tenmax/ad-placement-library-sdk-ios/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239546361,"owners_count":19656962,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-07T10:34:44.959Z","updated_at":"2025-02-18T20:34:58.734Z","avatar_url":"https://github.com/tenmax.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TenMax Mobile SDK for iOS/tvOS\n\nThis repository provides the guideline and examples to demonstrate how to use TenMax Mobile SDK to show AD on your iOS/tvOS app.\n\n## Prerequisites\n\nBefore using the SDK, please contact TenMax (app_support@tenmax.io) to\n\n- register you app bundle ID\n- obtain you app publisher ID\n\nThe bundle ID and publisher ID would be used to initiate the SDK.\n\n## Installation\n### Swift Package Manager\n\nThe [Swift Package Manager](https://swift.org/package-manager/) is a tool for automating the distribution of Swift code and is integrated into the Xcode.\n\n#### Xcode Project Integration\n\nGo to `File \u003e Add Package Dependencies...`, paste `https://github.com/tenmax/ad-placement-library-sdk-ios` into package URL. After the package is found, you can indicate the exact version of SDK. Then, click the `Add Package` to add the SDK package into your Xcode project.\n\n#### Swift Package Integration\n\nAdding TenMaxMobileAdsSDK as a dependency into the your `Package.swift` and indicating the SDK version.\n\n```swift\ndependencies: [\n    .package(url: \"https://github.com/tenmax/ad-placement-library-sdk-ios\", .upToNextMajor(from: \"0.0.1\"))\n]\n```\n\nNormally you'll need to add the `TenMaxMobileAdsSDK` target:\n\n```swift\n.product(name: \"TenMaxMobileAdsSDK\", package: \"TenMaxMobileAdsSDK\")\n```\n\nThe Package.swift sample like this,\n\n```swift\nlet package = Package(\n    name: \"YourPackageName\",\n    products: [\n        .library(name: \"YourPackageName\", targets: [\"YourTargetName\"]),\n    ],\n    dependencies: [\n      .package(url: \"https://github.com/tenmax/ad-placement-library-sdk-ios\", .upToNextMajor(from: \"0.0.1\"))\n    ],\n    targets: [\n        .target(\n            name: \"YourTargetName\",\n            dependencies: [\n              .product(name: \"TenMaxMobileAdsSDK\", package: \"ad-placement-library-sdk-ios\")\n            ],\n        ),\n    ]\n)\n```\n\n### Carthage\n\n[Carthage](https://github.com/Carthage/Carthage) is a decentralized dependency manager that builds your dependencies and provides you with binary frameworks. To integrate TenMaxMobileAdsSDK into your Xcode project using Carthage, specify it in your `Cartfile`:\n\n```ogdl\nbinary \"https://raw.githubusercontent.com/tenmax/ad-placement-library-sdk-ios/main/TenMaxMobileAdsSDK.json\"\n```\n\nAfter Carthage downloaded the `TenMaxMobileAdsSDK.xcframework` file, you can found out the file in the folder `./Carthage/Build`. Make sure you have added `TenMaxMobileAdsSDK.xcframework` to the \"Linked Frameworks and Libraries\" section of your target.\n\n## SDK Configuration\n\n### App Configuration\n\nUpdate your app's `info.plist` file to add `NSUserTrackingUsageDescription` key with a string value that will be showed on the dialog when user to request the app-tracking authorization.\n\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003c!DOCTYPE plist PUBLIC \"-//Apple//DTD PLIST 1.0//EN\" \"http://www.apple.com/DTDs/PropertyList-1.0.dtd\"\u003e\n\u003cplist version=\"1.0\"\u003e\n\u003cdict\u003e\n\t\u003ckey\u003eNSUserTrackingUsageDescription\u003c/key\u003e\n\t\u003cstring\u003eTracking usage description\u003c/string\u003e\n\t\u003ckey\u003eUIApplicationSceneManifest\u003c/key\u003e\n\u003c/dict\u003e\n\u003c/plist\u003e\n\n```\n\n### SDK initiation\n\nTenMax Mobile SDK must be initiated before use, thus, we recommend you to initiate it in your `AppDelegate` class. The SDK would run the initiation in an independent thread pool so won't increase your application launch time.\n\nThe publisher ID is provided by TenMax and the bundle ID must be the same as the value you registered in the [Prerequisites](#prerequisites) section.\n\n```swift\nimport TenMaxMobileAdsSDK\n\nclass AppDelegate: UIResponder, UIApplicationDelegate {\n\n    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -\u003e Bool {\n      TenMaxMobileSDK.initiate(\n        configuration: .init(publisherId: \"{publisher-id}\")) { spaces, error in\n          if let error {\n              print (error)\n          } else {\n              print (spaces)\n          }\n      }\n    }\n}\n```\n\nIf you do not initiate the SDK, every call to show ADs, the SDK would give you an error. The SDK initiation would load the AD information from the TenMax's server and try to obtain the iOS advertising ID (IDFA) for you. Now, you are ready to show AD.\n\n## Show ADs\n\n### Interstitial AD (iOS only)\n\nFirst, let show an interstitial AD (fullscreen AD) when you click the `Open Interstitial Ad` button. Assume your application's `HomeViewController` has three tabs: `InterstitialViewController`, `InlineBannerViewController`, and `ScreenBannerViewController`. In the `InterstitialViewController`, add following lines to show an interstitial AD when pressed the `Open Interstitial Ad` button:\n\n```swift\nimport TenMaxMobileAdsSDK\n\nclass InterstitialViewController: UIViewController {\n\n    private var tenMaxAd: TenMaxAd?\n\n    override func viewDidLoad() {\n      /** initialization for the OpenAD button */\n    }\n    \n    override func viewWillAppear(_ animated: Bool) {\n        super.viewWillAppear(animated)\n        \n        tenMaxAd = TenMaxMobileSDK.shared().interstitialAd(spaceId: \"{interstitial-space-id}\") { spaces, error in\n            if let error {\n                print (error)\n            } else {\n                print (spaces)\n            }\n        }\n    }\n    \n    override func viewWillDisappear(_ animated: Bool) {\n        super.viewWillDisappear(animated)\n        \n        tenMaxAd?.dispose()\n    }\n    \n    @objc func openAd(_ sender: UIButton) {\n        tenMaxAd?.show()\n    }\n}\n\n```\n\nThe AD presentation is asynchronous, thus, please keep the `TenMaxAdDisposable` object returned from the `interstitialAd` method. You can dispose (cancel) the presentation when the user switch to other tabs by calling `disposable.dipose()`. The SDK would cancel the presentation (if not presented yet) or remove the presentation and then clean up resources to reduce the memory usage.\n\n### Banner AD (iOS only)\n\nYou can show a banner AD on top of the screen or bottom of the screen. Even more, you can show both top and bottom banner on the same screen. However, the relationship between the banner and your app's UI is up to you.\n\nYou can call the `bannerAd` method to let SDK show the banner AD in the specified container.\n\n```swift\nimport TenMaxMobileAdsSDK\n\nclass ScreenBannerViewController: UIViewController {\n\n    private var screenTopAd: TenMaxAd?\n    \n    override func viewDidLoad() {\n      /** initialization for sub-views */\n    }\n    \n    override func viewWillAppear(_ animated: Bool) {\n        super.viewWillAppear(animated)\n        \n        screenTopAd = TenMaxMobileSDK.shared().bannerAd(spaceId: \"{banner-space-id}\", on: view, at: .top)\n        screenTopAd?.show()\n    }\n    \n    override func viewWillDisappear(_ animated: Bool) {\n        super.viewWillDisappear(animated)\n        \n        screenTopAd?.dispose()\n    }\n}\n```\n\nThe SDK would use this information to avoid duplication (see [Duplication Detection](#duplication-detection)).\n\n### Inline AD (supported iOS and tvOS)\n\nTo embed an inline AD into your app, you need to add a container into your layout. The SDK process the AD view based on `Auto Layout` system, thus, you should provide the constraints to indicate the relationship between your UIs and AD container correctly.\n\nIn your code, use the `inlineAd` method to embed the AD into the container. Then, the SDK would resize your container when the AD is loaded and ready to show.\n\n```swift\nimport TenMaxMobileAdsSDK\n\nclass InlineBannerViewController: UIViewController {\n\n    private let inlineAd = UIView()\n    private var tenMaxAd: TenMaxAd?\n\n    override func viewWillAppear(_ animated: Bool) {\n        super.viewWillAppear(animated)\n        \n        tenMaxAd = TenMaxMobileSDK.shared().inlineAd(spaceId: \"{inline-space-id}\", on: inlineAd)\n        tenMaxAd?.show()\n    }\n    \n    override func viewWillDisappear(_ animated: Bool) {\n        super.viewWillDisappear(animated)\n        \n        tenMaxAd?.dispose()\n    }\n}\n```\n\n[This is an experimental feature, cloud be changed in the later version.]\nYou can let the inline AD to (aspect) full fill a container with fixed size.\nFor example, the `inlineAdContainer` is a 300 x 200 fixed size container. \n\nThen, when initiate the inline AD, you can configure it with a options to specify which container to fill.\n\n```swift\noverride func viewWillAppear(_ animated: Bool) {\n    super.viewWillAppear(animated)\n    \n    tenMaxAd = TenMaxMobileSDK.shared().inlineAd(\n        spaceId: \"{inline-space-id}\", \n        on: inlineAd,\n        with: TenMaxInlineAdOptions()\n            .aspectFill(inlineAdContainer)\n    )\n    tenMaxAd?.show()\n}\n```\n\nNote, to use the aspect fill, you need to ensure the container's aspect ratio is the same as the AD.\nIf the aspect ratio does not match, if after scale, the calculated width or height exceeds the container's\nwidth or height, the AD could be cropped. You can know the case happened by listen the event (see the [callbacks and delegate](#callback-and-delegate) section).\n\n### Floating AD (iOS only)\n\nYou can let an AD keep floating on your app **until the app user close it**.\nTo show the floating app, call `floatingAd` with the root-view.\n\n```swift\nimport TenMaxMobileAdsSDK\n\nclass FloatingAdViewController: UIViewController {\n\n    private var tenMaxAd: TenMaxAd?\n\n    override func viewWillAppear(_ animated: Bool) {\n        super.viewWillAppear(animated)\n        \n        tenMaxAd = TenMaxMobileSDK.shared().floatingAd(\n            spaceId: \"{floating-space-id}\", \n            on: view,\n            options: TenMaxFloatingAdOptions()\n        )\n        tenMaxAd?.show()\n    }\n    \n    deinit {\n        tenMaxAd?.dispose()\n    }\n}\n\n```\n\n## Advanced topics\n\n### Timing and Naming Convention\n\nAD on different pages would have different prices. To collect needed information, TenMax Mobile SDK would monitor your application behavior. Thus, to avoid disturbing information collection, please follow these convention:\n\n- Always show ADs when or after the view will appear to ensure the size layout is already finished\n- Give unique name to the view controller that plays the role like a page, e.g., `InterstitialViewController`, `ScreenBannerViewController`, or `InlineBannerViewController` in the previous samples.\n\nIf you do not follow the convention and SDK can not collect the correct information, the SDK would refuse to show AD in the unexpected case.\n\n### Callback and Delegate\nEach method that show AD has two optional parameters: delegate and callback. The callback would be called immediately when the specified space ID is found or something wrong happened. You can provide the callback to know what happened during the setup.\n\nYou can provide the delegate to receive all the events of the entire presentation lifecycle. Here is a simple delegate to receive three important events:\n- `adViewableEventSent` - the user saw the AD for 1 second, and SDK would send viewable event to the TenMax server.\n- `adLoadingTimeout` - the AD loading timeout (maybe network is too slow) so the presentation is cancelled.\n- `adNotFound` - can not find an AD for the specified space so the presentation is cancelled.\n\n```swift\nclass SessionDelegate: TenMaxAdSessionDelegate {\n  private let view: UIView\n\n  init(view: UIView) {\n    self.view = view\n  }\n  \n  func adViewableEventSent(_ session: TenMaxAdSession) {\n      view.makeToast(\"viewable event sent\")\n  }\n\n  func adLoadingTimeout(_ session: TenMaxAdSession) {\n      view.makeToast(\"AD loading timeout\")\n  }\n\n  func adNotFound(_ session: TenMaxAdSession) {\n      view.makeToast(\"received adNoFill event\")\n  }\n}\n```\n\n### Duplication Detection\n\nFor most of ADs, the presentation must be unique on page. Thus, TenMax Mobile SDK would track the presentation requests. If SDK found the duplication, it would show the warning message for the app developer to fix the case. Also, TenMax would review your app to ensure you follow TenMax's rules.\n\n## Apple Privacy Survey for TenMax SDK\n\niOS publisher should provide the information that data their apps collect, including the data collected by third-party SDKs. For your convenience, TenMax SDK provides the information on its data collection in the [Apple Privacy Survey for TenMax SDK](Privacy.md).\n\n## app-ads.txt Support\n\nThe app-ads.txt file is a standardized document listing authorized digital sellers, introduced by the IAB to enhance transparency and combat fraud in the advertising ecosystem. It ensures seller legitimacy, safeguarding against fraudulent activities and domain misrepresentation.\n\nDevelopers are required to host this file at the root of their website. Brand advertisers and demand-side platforms (DSPs) access and analyze this file to validate seller authenticity when purchasing ad inventory programmatically through exchanges, supply-side platforms (SSPs), or ad networks.\n\nCopy the app-ads.txt file into the root of the developer website so that it's findable in the location.\n\n### app-ads.txt\n```text\ngoogle.com, pub-4338256439626145, DIRECT, f08c47fec0942fa0 \ngoogle.com, pub-9467144491537745, DIRECT, f08c47fec0942fa0\ntenmax.io, fadcc2c833, DIRECT\nfout.jp, 1537, DIRECT\nfout.jp, 113, DIRECT\n```\n\n## Issues and Contact\n\nIf you have any issue when using TenMax Mobile SDK, please contact app_support@tenmax.io. We would help you as soon as possible.\n\n## User Data Deletion Notice\n\nFor requests to delete the privacy data linked to users, please submit the request via [User Data Deletion Notice Form](https://forms.office.com/r/SnU40q6VmQ).\n\n## License\n\nTenMax\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftenmax%2Fad-placement-library-sdk-ios","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftenmax%2Fad-placement-library-sdk-ios","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftenmax%2Fad-placement-library-sdk-ios/lists"}