Usage (Android)

To use the SDK, you have to call the respective API.

Demo Activity

A demo activity is attached to the SDK. Unzip the file surfmeteranalytics_demo_$version.zip, and check out the MainActivity.java file to see how the app should be called. You can place this activity inside your existing app, or a new app. Just make sure you set up the dependencies correctly (see previous section).

Basic Example

In the simplest case, you need a builder for the API which can be launched in the onCreate method of your activity, and attach it to the existing ExoPlayer instance.

For example:

SurfmeterAnalytics mAnalytics = new SurfmeterAnalytics.Builder(
  this,
  mPlayer,
  "YOUR-API-KEY"
).build();

Advanced Examples

1. With Custom Metadata

You can attach custom metadata to your analytics data:

SurfmeterAnalytics mAnalytics = new SurfmeterAnalytics.Builder(
    this,
    mPlayer,
    "YOUR-API-KEY"
)
    .setMetadata(new HashMap<String, String>(2) {{
        put("userId", "some-user-id");
        put("assetId", "some-asset-id");
    }})
    .build();

These can be retrieved in the dashboard, and are very useful for segmenting your data for analysis purposes.

Warning

Please make sure that if you send personal data such as customer IDs, names, or email addresses, you have the necessary consent of the user to do so.

2. With Analytics Listener

You can listen to analytics events by implementing the SurfmeterAnalyticsListener interface:

public class YourActivity extends AppCompatActivity implements SurfmeterAnalyticsListener {
    private SurfmeterAnalytics mAnalytics;

    private void initAnalytics() {
        mAnalytics = new SurfmeterAnalytics.Builder(
            this,
            mPlayer,
            "YOUR-API-KEY"
        )
            .setAnalyticsListener(this)
            .build();
    }

    @Override
    public void onStateChanged(AnalyticsState state) {
        Log.d("YourActivity", "Analytics state changed: " + state);
    }

    @Override
    public void onSendingData() {
        Log.d("YourActivity", "Analytics is sending data");
    }

    @Override
    public void onError(@NonNull AnalyticsException error) {
        Log.e("YourActivity", "Analytics error: " + error);
    }

    @Override
    public void onLog(@NonNull int level, @NonNull String tag, @NonNull String message) {
        Log.d("YourActivity", "Analytics log: " + message);
    }
}

3. With Connection Detail Tracing

To enable detailed network connection tracing:

SurfmeterAnalytics mAnalytics = new SurfmeterAnalytics.Builder(
    this,
    mPlayer,
    "YOUR-API-KEY"
)
    .enableConnectionDetailTracing()
    .build();

This tracks information from the WiFi connection, in particular the (B)SSID and the IP address. If additional permissions are given (ACCESS_WIFI_STATE), we can also obtain the signal strength.

4. With Custom Sending Interval

You can customize how often the analytics data is sent:

SurfmeterAnalytics mAnalytics = new SurfmeterAnalytics.Builder(
    this,
    mPlayer,
    "YOUR-API-KEY"
)
    .setSendingInterval(30) // send every 30 seconds
    .build();

Lifecycle Management

Make sure to properly handle the analytics lifecycle:

// Stop analytics when done
@Override
protected void onDestroy() {
    super.onDestroy();
    if (mAnalytics != null) {
        mAnalytics.finish();
    }
}

// Or abort with reason if needed
private void handleError() {
    if (mAnalytics != null) {
        mAnalytics.abort("Player error occurred");
    }
}

Instrumented Usage

You can also call the demo activity with adb using the following example command:

adb shell am start -n "com.aveq.surfmeteranalyticsdemo/.MainActivity" \
  --ez autoRunTest true \
  --el maxTestDuration 10000 \
  --es manifestUri "https://example.com/manifest.mpd"

Note that these intent parameters are directly passed to the quality test SDK; check the demo app source code for more info on how they are handled.

Finally, we provide a shell script to run an Analytics test using the above call, which waits for the test to finish and then exits. See ./run_analytics_test.sh for more info.

API Docs

Please refer to the documentation in docs for more details.