Icon Ad Integration

1. The endpoint

Send a GET request with your parameters in the query string.

It returns an HTML page, not JSON. Load it directly in an Android WebView or iOS WKWebView — no parsing or rendering needed on your side.

2. Full example URL

Replace YOUR_API_KEY with the key we provide:

3. Parameters

Only key is mandatory. The more targeting values you send, the better the ad we can pick — which means a higher click rate for you.

4. Try it right now

Open any example below in a browser — no setup needed:

Prefer a form? Use the interactive URL builder to set parameters, preview the ad at different slot sizes, and copy the finished URL.

5. Android

WebView ad = findViewById(R.id.adSlot);
ad.getSettings().setJavaScriptEnabled(true);
ad.setBackgroundColor(Color.TRANSPARENT);

// IMPORTANT: store link must open outside the WebView
ad.setWebViewClient(new WebViewClient() {
  @Override
  public boolean shouldOverrideUrlLoading(WebView v, WebResourceRequest r) {
    startActivity(new Intent(Intent.ACTION_VIEW, r.getUrl()));
    return true;
  }
});

ad.loadUrl("https://ads.welcomead.com/api/v1/ad/view?bundle=" + getPackageName()
    + "&deviceid=" + deviceId + "&tag=games&format=icon&size=120x150");

6. iOS

let ad = WKWebView(frame: slot.bounds)
ad.isOpaque = false
ad.backgroundColor = .clear
ad.navigationDelegate = self
ad.load(URLRequest(url: URL(string:
  "https://ads.welcomead.com/api/v1/ad/view?bundle=\(Bundle.main.bundleIdentifier!)&deviceid=\(deviceId)&tag=games&format=icon&size=120x150")!))

// IMPORTANT: store link must open outside the WebView
func webView(_ w: WKWebView, decidePolicyFor n: WKNavigationAction,
             decisionHandler d: @escaping (WKNavigationActionPolicy) -> Void) {
  if n.navigationType == .linkActivated, let u = n.request.url {
    UIApplication.shared.open(u); d(.cancel); return
  }
  d(.allow)
}

7. Checking the response

On no fill we return an empty transparent page — never an error page — so a failed request can never show broken content inside your app.

8. What happens automatically

• Ad selection — we pick the highest-performing ad for your category, tags and placement.
• Rendering — icon, app name and Install button, sized to your WebView, transparent background.
• Impression tracking — counted the moment the ad appears.
• Click tracking — recorded, then the user is redirected to the store page.

Because we render the ad, we can improve the design or add new formats without you shipping an app update.

9. Reporting installs

When an app that we advertised gets installed, tell us with one call. We match on the device ID and the package name, so send the same deviceid you used on the ad request.

An install is attributed only if that app's ad was clicked from that device within the last 7 days. This is standard click-through attribution — an impression on its own is not enough. In WebView mode the click goes through us automatically; in JSON mode you must open the click_url we return instead of linking straight to the store.

GET https://ads.welcomead.com/api/v1/ad/install
      ?deviceid=device-abc-123
      &package_name=com.example.game

• Calling twice never counts twice — each device and package pair produces at most one install, enforced in the database.
• A 404 is normal — it just means the install is not ours. Report every install you detect and let us decide.
• The window restarts on every click — if the user taps the ad again, you get another 7 days.
• GET or POST — both work the same way.

Once an install is counted, we stop serving that app to that device, and the install appears in the advertiser's report the same day.