How the SDK Works

Step 1. Load Basic Configuration

Basic configuration—like which ad networks to use, credentials, and segmentation rules—are returned by the /start endpoint. When you call startWithPublisherID:, Heyzap's SDK first loads this data from an on-disk cache, then gets the most up-to-date version from the server.

By first loading from an on-disk cache, we're able to get the SDK started within milliseconds, and the SDK will continue to work even if Heyzap's servers are down or there's an interruption in internet connectivity.

start diagram

Step 2. Load the Waterfall

When the SDK is started, it also loads the order of networks to fetch from and show ads for (the "waterfall"). This is first loaded from the /mediate endpoint. If the request fails, we'll load from an on-disk cache (again, allowing the SDK to function even if Heyzap's servers are down).

Each time you show an ad, the SDK makes a new request to /mediate to get a new waterfall.

mediate diagram

Step 3. Fetch Ads

When you call fetch, our SDK will consult the ordered list of networks returned in Step 2. The first ad network will be initialized (if it hasn't been already) and our SDK will request that the third party network load an ad. Each ad network is given 10 seconds to load before we'll proceed to the next ad network.

On iOS, we'll stop initializing and loading ads after 2 ad networks have loaded an ad.

Having two networks loaded provides a safety buffer if your app shows several ads quickly. Not initializing networks until they need to fetch an ad reduces CPU, memory, disk and bandwidth usage.

On Android, we'll continue to load ads from all networks. We're looking into switching to the iOS model of loading ads to reduce disk and bandwidth usage, but don't have anything concrete planned.

fetch diagram

Step 4. Show Ads

When you call show, our SDK will consult the ordered list of networks returned in Step 2. We'll ask each network if they have an ad ready to show.

In the diagram below, SDK A reports that it doesn't have an ad, so we continue on to SDK B. Since it has an ad, we ask it to show an ad, and don't get to SDK C.

show diagram

For this example, Heyzap will report fill rate as follows:

  • SDK A was considered not to fill, because they were given a chance to show an ad, but didn't have one available.
  • SDK B was considered to fill, because they showed an ad.
  • SDK C is not considered for this particular show, because they were never given the chance to show an ad.