{"id":13998293,"url":"https://github.com/hiddevdploeg/Billboard","last_synced_at":"2025-07-23T06:31:04.695Z","repository":{"id":177888153,"uuid":"660690919","full_name":"hiddevdploeg/Billboard","owner":"hiddevdploeg","description":"a Swift Package that lets you add beautiful and privacy-friendly Ads to your app. These are Advertisements for Indies, by Indies.","archived":false,"fork":false,"pushed_at":"2024-11-29T11:07:11.000Z","size":134,"stargazers_count":542,"open_issues_count":5,"forks_count":28,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-11-29T11:33:11.745Z","etag":null,"topics":["ads","advertising","apple","banner","indiedev","ios","ipad","swift","swift-package-manager","swiftui"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hiddevdploeg.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","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},"funding":{"custom":["https://www.paypal.me/hiddevdploeg","https://monzo.me/hiddevanderploeg"]}},"created_at":"2023-06-30T15:40:48.000Z","updated_at":"2024-11-29T11:06:14.000Z","dependencies_parsed_at":null,"dependency_job_id":"d5d65a70-d8ae-416f-8af6-54fc289fd805","html_url":"https://github.com/hiddevdploeg/Billboard","commit_stats":{"total_commits":99,"total_committers":10,"mean_commits":9.9,"dds":"0.18181818181818177","last_synced_commit":"e40ac4bf7b8477b5d15209af5321f4a7c230fa4b"},"previous_names":["hiddevdploeg/billboard"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hiddevdploeg%2FBillboard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hiddevdploeg%2FBillboard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hiddevdploeg%2FBillboard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hiddevdploeg%2FBillboard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hiddevdploeg","download_url":"https://codeload.github.com/hiddevdploeg/Billboard/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227115289,"owners_count":17733159,"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":["ads","advertising","apple","banner","indiedev","ios","ipad","swift","swift-package-manager","swiftui"],"created_at":"2024-08-09T19:01:33.045Z","updated_at":"2024-11-30T00:31:23.041Z","avatar_url":"https://github.com/hiddevdploeg.png","language":"Swift","funding_links":["https://www.paypal.me/hiddevdploeg","https://monzo.me/hiddevanderploeg"],"categories":["Swift"],"sub_categories":[],"readme":"![Header Photo@2x](https://github.com/hiddevdploeg/Billboard/assets/5016984/7620bddc-c758-4a54-bac5-bd4326ffae2c)\n\n# Billboard\nBillboard is a module that enables the incorporation of advertisement highlights for applications created by independent developers. Its unique feature lies in its execution of ads without the use of tracking measures or unwanted cookies. This way, your user can still get annoyed by advertisements without the nasty bits, and therefore you get a free \"Remove Ads\" selling point for your premium tier.\n\n**These ads do NOT generate revenue or track anything**\n\n### In Short:\n- 🚫 No tracking/cookies\n- 📲 Customizable Ad overlay in SwiftUI\n- 🔧 Flexible configuration\n- 🎨 Use the default list of high-quality Ads or use your own source\n- 🌈 Various Ad types\n- 🎁 Ideal to get an ad-free premium tier.\n\n\n## Installation\nReady to use on iOS 16+, tvOS 17+ and visionOS 1+.\n\n1. In Xcode, select **Add Packages…** from the File menu.\n2. Enter `https://github.com/hiddevdploeg/Billboard` in the search field.\n3. Click **Add Package** (Set the Dependency Rule to Up to Next Major Version)\n4. After adding the package, you will be able to import Billboard in your project by using.\n\n```swift\nimport Billboard\n```\n\n## How to display an Ad\n\nBillboard provides an easy way to present an ad overlay on any SwiftUI `View`. Here's a simple example:\n\n```swift\n\n@State private var showRandomAdvert = false\n\nContentView()\n    .showBillboard(when: $showRandomAdvert) {\n        // Replace this view with your Paywall\n        Text(\"Your Paywall goes here\")\n    }\n\n```\n\nAlternatively, you can customize the `BillboardView` and position it in any way that suits your app. This view takes a `BillboardAd`, a `BillboardConfiguration` (Optionally), and a view that represents your paywall:\n\n```swift\n\n@State private var advertisement: BillboardAd? = nil\n@StateObject var viewModel = BillboardViewModel()\n\n\nContentView()\n    .task {\n        let newAdvert = try? await viewModel.fetchRandomAd()\n        advertisement = newAdvert\n    }   \n    .fullScreenCover(item: $advertisement) { advert in\n        BillboardView(advert: advert, paywall: { Text(\"Paywall\") })\n    }\n\n```\n\n**TIP**: When you're running a debug version of your app you can tap on the timer to show a dismiss button right away.\n![Examples@2x](https://github.com/hiddevdploeg/Billboard/assets/5016984/b9b9fdc4-5da0-47d7-8ae2-3c22c874620b)\n\n\n## BillboardBannerView\n\nIf you don't fancy a fullscreen view but prefer a smaller banner to display within your content you can do that now too! Simple add a `BillboardBannerView` wherever you like. \n\n```swift\n@State private var advert: BillboardAd? = nil\nContentView()\n    .safeAreaInset(edge: .bottom) {\n        if let advert {\n            BillboardBannerView(advert: advert)\n                .padding()\n        }\n    }\n```\n\nBy default it comes with a shadow, which you can opt-out from by changing the `includeShadow` value. Here's an example on how you could include a `BillboardBannerView` in your list:\n\n```swift\n@State private var advert: BillboardAd? = nil\n\nList {\n    if let advert {\n        Section {\n            BillboardBannerView(advert: advert, includeShadow: false)\n                .listRowBackground(Color.clear)\n                .listRowInsets(.init(top: 0, leading: 0, bottom: 0, trailing: 0))\n        }\n    }\n    \n    // Rest of the list...\n}\n\n```\n\nYou can also hide the dismiss button to have a persistent banner, by adding `hideDismissButtonAndTimer: true` to your `BillboardBannerView`.\n\n![BillboardBannerExamples](https://github.com/hiddevdploeg/Billboard/assets/5016984/259603dd-3160-4552-a3da-990ecb33afd4)\n\n## Configuration\n\nBillboard lets you define some configurations to fit your needs better.\n\n``` swift\npublic struct BillboardConfiguration {\n    \n    /// The URL pointing to the JSON in the `BillboardAdResponse` format.\n    public let adsJSONURL: URL?\n    \n    /// Enable or disable haptics\n    public let allowHaptics: Bool\n    \n    /// The duration of the advertisement\n    public let duration: TimeInterval\n    \n    /// Provide a list of Apple ID's that you want to exclude from showing up (e.g. your own app)\n    public let excludedIDs : [String]\n    \n    public init(adsJSONURL: URL? = URL(string:\"https://billboard-source.vercel.app/ads.json\"),\n                allowHaptics: Bool = true,\n                advertDuration: TimeInterval = 15.0, excludedIDs: [String] = []) {\n        self.adsJSONURL = adsJSONURL\n        self.allowHaptics = allowHaptics\n        self.duration = advertDuration\n        self.excludedIDs = excludedIDs\n    }\n}\n```\n\nThis also allows you to use your own source of ads that follow the `BillboardAdResponse` format.\n\n```swift\n\n@State private var showRandomAdvert = false\n\nlet config = BillboardConfiguration(\n    adsJSONURL: URL(string: \"YOUR-OWN-SOURCE\"),\n    allowHaptics: false,\n    advertDuration: 30.0,\n    excludedIDs: [\"1234567890\"]\n)\n\nContentView()\n    .showBillboard(when: $showRandomAdvert, configuration: config) {\n        // Replace this view with your Paywall\n        Text(\"Your Paywall goes here\")\n    }\n\n```\n\n\n## BillboardAdResponse\nHere's an example of how your source list could look like.\n\n```json\n{\n  \"ads\" : [\n    {\n      \"appStoreID\" : \"1574243765\",\n      \"name\" : \"NowPlaying\",\n      \"title\": \"Learn everything about any song\",\n      \"description\" : \"A music companion app that lets you discover the stories behind and song, album or artist.\",\n      \"media\": \"https://pub-378e0dd96b5343108a04317ebddebb4e.r2.dev/nowplaying.png\",\n      \"backgroundColor\" : \"344442\",\n      \"textColor\" : \"EFDED7\",\n      \"tintColor\" : \"EFDED7\",\n      \"fullscreen\": false,\n      \"transparent\": true,\n      \"adCategory\": \"music\"\n    }\n  ]\n}\n\n```\n\n![Ad Example@2x](https://github.com/hiddevdploeg/Billboard/assets/5016984/0351d110-1f51-45ab-9d61-497d87653dfa)\n\n\n## Ad Guidelines \u0026 Requirements\nSubmit your app to be featured as an Ad for everyone using the Billboard package to display Advertisements.\nEach ad will be reviewed before inclusion.\n\n**[You can submit your app here](https://forms.gle/nWV4dT3taBF62WXbA)**\n\nFeel free to use the [Billboard template for Figma](https://www.figma.com/community/file/1257700620161188779) to tweak and preview the promo.\n\n### Ad Requirements\n- **Apple ID of App**: The Apple ID is a 9- or 10-digit number found in your App Store URL or in App Store Connect.\n- **Name of App**: The name of the app you're promoting\n- **Title**: The advertisement headline (maximum 25 characters).\n- **Description**: The advertisement description (maximum 140 characters).\n- **Media**: The image used in your advertisement.\n\n### Media Guidelines\n- Image should be a minimum of 1280x1280 in resolution.\n- The image should not contain any text outside of the visual content.\n- Avoid using your App Icon as the image (as it's already displayed by default).\n- Provide an image with no background or has a single color (avoid gradients).\n- Photos are allowed as well but will be displayed differently.\n- Try and submit an evergreen image that represents your app, show it's good practice to avoid showing UI that gets outdated fast. \n\n## Ad Types\nThe media of an ad will be displayed covering the whole view when `BillboardAd.fullscreen` is set to `true`. This works great if the media is a photo instead of a visual. Please consider that the photo's subject must be in the center, which will ensure it's always visible.\n\n![AdTypes@2x](https://github.com/hiddevdploeg/Billboard/assets/5016984/c7e2f96a-6368-4807-9c81-7dddd008d5ad)\n\n\n\n## FAQ\n### Which Ads are presented when I use the default config\nYou'll find a list of all currently used ads in the example app.\n\n## Special thanks to\n[tundsdev](https://twitter.com/tundsdev) for CachedImage implementation\n\n## Authors\nThis library is created by [Hidde van der Ploeg](https://hidde.design). Feel free to reach out on [Twitter](https://twitter.com/hiddevdploeg) or [Mastodon](https://mastodon.design/@hidde).\n\n## License\nBillboard is available under the MIT license.\n\n\n    THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS\n    FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR\n    COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER\n    IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\n    CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhiddevdploeg%2FBillboard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhiddevdploeg%2FBillboard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhiddevdploeg%2FBillboard/lists"}