README.md

Bridgewell SDK for Android

Links to the full documentation

Version: 1.0

Note: All integration examples are written in Kotlin. If you’re using Java please convert them to corresponding Java code

Table of Contents

• Requirements
• General Setup
  • 1. SDK installation
    • a. Using Maven Central
    • b. Using the .aar file
  • 2. SDK initialization
    • a. Set your account credentials
    • b. Initialize SDK
    • c. Geolocation sharing
  • 3. Update Your Android Manifest
• SDK Usage
  • 1. WebView API usage
  • 2. Banner ads
    • a. Display normal banner
    • b. Sticky banner
• About

Requirements

• Android 8.0 (SDK version 26) or newer
• Mobile phone with Google Play Services
• Android Studio 2023.3.1 or newer
• Gradle 8.2 or newer

General setup

1. SDK installation

a. Using Maven Central

1. Add the dependency:

dependencies {
	implementation("com.bridgewell:bwmobile:1.3.0")
}

2. Sync your project.

b. Using the .aar file

1. Place the .aar file into your project's app/libs folder: /app/libs/bwmobile.aar
2. Add this code to the dependencies block in your application's build.gradle file:

dependencies {
    implementation fileTree(dir: "libs", include: ["*.jar", "*.aar"])
    implementation files('libs/bwmobile.aar')
}

3. Sync your project.

2. SDK initialization

a. Set your account credentials

After obtaining a BW server (e.g., the Rubicon Server), add its details to BW Mobile:

BWMobile.getInstance().setAccountId("YOUR_ACCOUNT_ID")

b. Initialize SDK

Once you have an account ID and host server, initialize the BW SDK as follows:

BWMobile.getInstance().initialize(
   context,
   object : OnInitializationListener {
       override fun onSuccess() {
	// Called when the SDK is initialized successfully
       }

       override fun onFailed(msg: String) {
	// Called if the SDK initialization fails
       }
   }
)

c. Geolocation sharing

• If this flag is set to true and the app collects the user's geographical location data, BW Mobile will send this data to the BW server.

• If this flag is false or the app does not collect location data, BW Mobile will not include any geographical location information in the call to the BW server.

  BWMobile.getInstance().setShareGeoLocation(true)
  val isShareGeoLocation = BWMobile.getInstance().getShareGeoLocation()

---

3. Update your Android manifest

1. Before starting, integrate the SDK by updating your AndroidManifest.xml with the following permissions:

    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="com.google.android.gms.permission.AD_ID"/>
    <uses-permission android:name="android.permission.READ_PHONE_STATE" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />

• ACCESS_COARSE_LOCATION and ACCESS_FINE_LOCATION allow the device to send user location data for ad targeting, which can increase revenue by making impressions more valuable to buyers.
• READ_PHONE_STATE allows the Web View API to collect device data.

2. Configure your app by following the instructions for the Google Mobile Ads SDK.

SDK usage

1. Web View API

This section explains how to obtain device information and make it available in the WebView interface.

Prerequisites

• Declare the permissions mentioned in section 3

Register the web view

BWMobile.getInstance().setShareGeoLocation(true)
BWMobile.getInstance().registerContentWebViewWithAdInfo(webView)

This should be done as early as possible, such as in the onCreate() method of your MainActivity

override fun onCreate(savedInstanceState: Bundle?) {
   super.onCreate(savedInstanceState)

   // Enable geographical location data
   BWMobile.getInstance().setShareGeoLocation(true)

   // Register the web view.
   BWMobile.getInstance().registerContentWebViewWithAdInfo(webView)

   adWrapperView.addView(webView)
   webView.loadUrl(URL)
}

Result:

2. Banner ads

You can use the BridgeWell SDK to monetize your app with a custom ad server or even without one. Use the InAppApi to obtain targeting keywords for use with your custom ad server and display the winning bid without relying on a primary ad server and its SDK.

a. Display normal banner

Sample code:

// Create an instance of InAppApi
val adApi: InAppApi = InAppApi()

// perform to fetch and load ad
adApi.createBwsBannerAd(
   context = context,
   viewPager = yourViewPager, // optional
   model = DisplayBannerModel(
       configId = CONFIG_ID,
       width = 300,
       height = 300,
       refreshTimeSeconds = 300
   ),
   viewContainer = viewContainer,
   listener = object: BwsAdViewListener {
       override fun onAdViewStartLoad(bannerView: BwsAdView?) {}
       override fun onAdViewLoaded(bannerView: BwsAdView?) {}
       override fun onAdViewDisplayed(bannerView: BwsAdView?) {}
       override fun onAdViewFailed(bannerView: BwsAdView?, exception: AdException?) {}
       override fun onAdViewClicked(bannerView: BwsAdView?) {}
       override fun onAdViewClosed(bannerView: BannerView?) {}
   }
)

Result:

Note: - If you display the ad in a ViewPager, you need to set `offscreenPageLimit` to ensure stable ad display, or pass the ViewPager into `createDisplayBannerAd` - You also need pass some necessary parameters to createDisplayBannerAd() function

Parameter	Explain	Detail
context	Instance of Context	-
viewPager	The view pager contains the ad item	[Optional]: Skip this parameter if you've already set offscreenPageLimit on your ViewPager or if your ad is not displayed inside a ViewPager.
model	Contains information to generate the ad	ConfigId: an ID of a Stored Impression on the Bw server refreshTimeSeconds: refresh time for each fetchDemand call in second width: Width of the ad Height: Height of the ad
viewContainer	The view to which the ad will be added.	-
listener	Callback listener (BwsAdViewListener)	onAdViewStartLoad: Called when the ad starts loading onAdViewLoaded: Called when the ad is loaded successfully onAdViewDisplayed: Called when the ad is displayed onAdViewFailed: Called when the ad fails to load onAdViewClicked: Called when the ad is clicked onAdViewClosed: Called when the ad is closed

b. Sticky banner

Sample code:

// Create an instance of InAppApi
val adApi: InAppApi = InAppApi()

// perform to fetch and load ad
adApi.createBwsRightSideStickyAd(
   context = context,
   model = DisplayBannerModel(
       configId = CONFIG_ID,
       width = 300,
       height = 300,
       refreshTimeSeconds = 300
   ),
   viewContainer = viewContainer,
   listener = object: BwsAdViewListener {
       override fun onAdViewStartLoad(bannerView: BwsAdView?) {}
       override fun onAdViewLoaded(bannerView: BwsAdView?) {}
       override fun onAdViewDisplayed(bannerView: BwsAdView?) {}
       override fun onAdViewFailed(bannerView: BwsAdView?, exception: AdException?) {}
       override fun onAdViewClicked(bannerView: BwsAdView?) {}
       override fun onAdViewClosed(bannerView: BwsAdView?) {}
   }
)

Result:

Note: - You also need pass some necessary parameters to `createStickyBannerAd()` function

Parameter	Explain	Detail
context	Instance of Context	-
model	Contains information to generate the ad	ConfigId: an ID of a Stored Impression on the Bw server refreshTimeSeconds: refresh time for each fetchDemand call in second width: Width of the ad Height: Height of the ad
listener	Callback listener (BannerAdListener)	onAdViewStartLoad: Called when the ad starts loading onAdViewLoaded: Called when the ad is loaded successfully onAdViewDisplayed: Called when the ad is displayed onAdViewFailed: Called when the ad fails to load onAdViewClicked: Called when the ad is clicked onAdViewClosed: Called when the ad is closed

About

Copyright 2019 Bridgewell | All Rights Reserved