SDK Integration - Best Practices

Following these best practices will help ensure you make the most money possible with CommuteStream.

Overview

What makes us different than other ad networks is something we call "Ad Optimization", and it's why we pay you more. It's easy to do, and just involves adding a few one-line method calls throughout your app. This provides us with information about how users interact with the transit system, which our system then uses to deliver timely and highly relevant ads to your users.

This document is intended to show actual use cases -- demonstrating how these methods should be used in the context of an actual app. More details on these methods can be found in the SDK documentation which can be foundhere for Androidorhere for iOS.

Bottom line: Developers who make the best use of our API calls, help us serve better ads, and earn the highest compensation per ad impression... all while providing a better experience for their users.

Handling Multiple Stop Arrival Times

It is common for tracking apps to display arrival time information for more than one transit stop within the same view. The stops may be geographically linked (nearby), or they could just be a list of favorite stops selected by that user. Whatever the case, if your app is displaying arrival times for one or more transit stops, it should be callingtrackingDisplayedonce for each transit stop presented to the user.

Nearby Stops Example

Here we have an app showing arrival times for the two closest transit stops. One a train stop and the other a bus stop. For us, the important information here is that the user is in some way "interested" in tracking these stops.

Somewhere in the code that creates this view we might have:

Android:
CommuteStream.trackingDisplayed("cta", routeID1, stopID1);
CommuteStream.trackingDisplayed("cta", routeID2, stopID2);
iOS:
[[CommuteStream open] trackingDisplayed:@"cta" routeID:routeID1 stopID:stopID1];
[[CommuteStream open] trackingDisplayed:@"cta" routeID:routeID2 stopID:stopID2];
The routeIDs and stopIDs are returned by CTA'sBus andTrain tracker APIs in another part of the code... The CTA uses field names "rt" and "stpid" in both APIs.

It is important to note that you don't need to report any arrival time data, just the stops and routes for which data is being displayed to the user.

List of Favorites Example

Here we have an app showing arrival times for three separate transit stops that are saved as "Favorites".

Somewhere in the code that creates this view we might have:

Android:
CommuteStream.trackingDisplayed("cta", routeID1, stopID1);
CommuteStream.trackingDisplayed("cta", routeID2, stopID2);
CommuteStream.trackingDisplayed("cta", routeID3, stopID3);
iOS:
[[CommuteStream open] trackingDisplayed:@"cta" routeID:routeID1 stopID:stopID1];
[[CommuteStream open] trackingDisplayed:@"cta" routeID:routeID2 stopID:stopID2];
[[CommuteStream open] trackingDisplayed:@"cta" routeID:routeID3 stopID:stopID3];
The routeIDs and stopIDs are returned by CTA'sBusandTraintracker APIs in another part of the code... The CTA uses field names "rt" and "stpid" in both APIs.

Actually, in this case it's more likely you would have a loop instead of the three distinct calls show above -- looping though the list of favorites and callingtrackingDisplayedfor each one.

Handling Multiple Routes For One Stop

It is often the case that one transit stop will service a number of different routes. For example, the Belmont train station provides access to three different trains; Red Line, Brown Line and Purple Line. Buses are no exception with some stops being used for up to 6 or more bus routes.

When multiple route arrival times for one stop are being displayed, it is important to determine WHICH route (train or bus) the user is most interested in.

One Stop/Multiple Routes Example

Here we have an app showing arrival times for various train lines approaching the Belmont stop. However, this app is also showing them under the header "Red Line", meaning the route of interest has been gathered from the user.

If the route of interest can be determined, make only onetrackingDisplayedcall for that particular route and no others.

For this app the code would look something like the following:

Android:
CommuteStream.trackingDisplayed("cta", routeOfInterest, stopID);
iOS:
[[CommuteStream open] trackingDisplayed:@"cta" routeID:routeOfInterest stopID:stopID];
The routeIDs and stopIDs are returned by CTA'sBusandTraintracker APIs in another part of the code... The CTA uses field names "rt" and "stpid" in both APIs.

Making Calls with Incomplete Transit Data

Many CommuteStream SDK calls require three parameters (agency_info, route_id, stop_id). This data helps us determine the most relevant ads to send each app user. However, there may be instances where you are displaying useful transit data to a user, but you don't have all three parameters. In these cases, it is best to set a value of null or nil for the each parameter with missing information.

Incomplete Data Example

This app is displaying a CTA status alert that effects the Red Line as a whole, but does not address a specific stop.

In this case, the value for the stop parameter would be set to null or nil as shown in this sample code:

Android:
CommuteStream.alertDisplayed("cta", routeID, null);
iOS:
[[CommuteStream open] alertDisplayed:@"cta" routeID:routeID stopID:nil];
The GTFS routeIDs and stopIDs are used with the CTA'sAlert API.

The important thing to remember is that SOME data is better than NO data as long as the information being displayed is relevant to the user's commute.

Complete AND Incomplete Data Example

This app is displaying two status alerts that relate to one transit route, the Green Line. However, one alert addresses the whole route in general, and the other includes information about a specific stop.

In this instance, it is important to make separatealertDisplayedcalls; each providing as much information possible.

It might look something like the following:

Android:
CommuteStream.alertDisplayed("cta", routeID, null);
CommuteStream.alertDisplayed("cta", routeID, alert2StopID);
iOS:
[[CommuteStream open] alertDisplayed:@"cta" routeID:routeID stopID:nil];
[[CommuteStream open] alertDisplayed:@"cta" routeID:routeID stopID:alert2StopID];
The GTFS routeIDs and stopIDs are used with the CTA'sAlert API.

Once again, for any CommuteStream SDK call that provides transit data, enter as much data as possible and set parameters for which there is no data to null or nil.

Thanks for Reading

By following the best practices outlined above, developers and publishers can earn $4 RPM and provide an improved experience for their users.

Please feel free tocontact uswith any questions or assistance in setting up your transit app for maximum revenue.