Awesome
Ahoy Android
Visit attribution library for Android that works on top of Rails Ahoy foundation.
:tangerine: Battle-tested at Instacart
:waning_gibbous_moon: User visit tracking
:inbox_tray: Visit attribution through UTM & referrer parameters
Motivation
No matter which Analytics solution we tried, we always use our own database as the source of truth. Ahoy Android stores visit attribution (UTM & referrer parameters) in your data storage of choice (through Ahoy on Rails) and allows to associate business data (e.x. user and order records), with visits & funnels (attributions).
Using ahoy-android
There are just a few steps to get started using ahoy-android.
Installation
Add this to your application's build.gradle
file:
repositories {
maven {
url "https://jitpack.io"
}
}
dependencies {
implementation 'com.github.instacart:ahoy-android:latest.version.here'
}
where latest.version.here
is the latest released version:
Visit
Visit corresponds to user's session in the app. Visit's extra parameters (UTMs, referrer) are stored for the duration of the visit. After visit expires extra parameters are cleared.
Tracking visits
public class App extends Application {
@Override public void onCreate() {
super.onCreate();
boolean autoStart = /* start Ahoy on first Activity::onCreate invocation */ true;
long visitExpiration = 60 * 60 * 1000;
DeviceInfo deviceInfo = new SimpleDeviceInfo();
Retrofit2Delegate delegate = Retrofit2Delegate.factory("http://www.example.com", visitExpiration, deviceInfo, true);
AhoySingleton.init(this, delegate, autoStart);
}
}
AhoySingleton
is a convenience wrapper. See RxAhoy
for visits stream. For Dependency Injection, create Ahoy
instance directly.
To start Ahoy manually, pass autoStart = false
and call Ahoy.ensureFreshVisit
when appropriate. Ahoy stops refreshing visits when application is backgrounded. If initialized with autoStart = false
, it needs to be restarted.
Please use our Sample and Tests projects for reference.
UTMs
To save additional parameters (UTM, referrer):
Map<String, Object> params = ...
// starts a new visit
Ahoy.newVisit(params)
Visits & Signups
Ahoy associates signups and signins with visits using Ahoy-Visitor
and Ahoy-Visit
headers. E.x. okhttp3 application interceptor passing them to backend:
public class AhoyRequestInterceptor implements okhttp3.Interceptor {
private Ahoy ahoy;
@Override public Response intercept(Chain chain) throws IOException {
if (ahoy == null) {
return chain.proceed(chain.request());
}
String visitToken = ahoy.visit().visitToken();
Request request = chain.request();
Builder builder = request.newBuilder();
if (!TextUtils.isEmpty(visitToken)) {
builder.header("Ahoy-Visit", visitToken);
}
builder.header("Ahoy-Visitor", ahoy.visitorToken());
return chain.proceed(builder.build());
}
public void setAhoy(Ahoy ahoy) {
this.ahoy = ahoy;
}
}
Ahoy & other Analytics solutions
At Instacart we use Segment to send events a Date Warehouse and Amplitude. Whenever we make requests to Segment we include Ahoy visit token and extra parameters.
License
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.