Skip to content

Usage Instructions

All the steps in this page are mandatory for succesfull integration of the Adori SDK.

Step 1: Setup Exoplayer

Use Adori's AdoriMediaCodecAudioRendererFactory instead of Exoplayer's DefaultRenderersFactory.

1.1: Create RenderersFactory

1
2
3
4
// DefaultRenderersFactory defaultRenderersFactory = new DefaultRenderersFactory(this);

AdoriMediaCodecAudioRendererFactory adoriMediaCodecAudioRendererFactory 
    = new AdoriMediaCodecAudioRendererFactory(this);

Warning

If you do not use DefaultRenderersFactory and want Adori to support a customized version please contact Adori Support.

1.2: Create player

1
2
3
4
// SimpleExoPlayer player = new Builder(this, defaultRenderersFactory).build();

SimpleExoPlayer player = new Builder(this,
    adoriMediaCodecAudioRendererFactory).build();

Step 2: Setup AdoriTagsService

AdoriTagsService extracts embedded tags from the audio and interacts with Adori APIs.

2.1: Create AdoriTagsService

AdoriTagsService needs your application context for initialization.

1
AdoriTagsService adoriTagsService = new AdoriTagsService(context);

Info

Make sure this instance is a singleton.

2.2: Attach player

AdoriTagsService needs an instance of player and the AdoriMediaCodecAudioRendererFactory to extract tags from the audio. See Step 1: Setup Exoplayer for instantiating the player.

1
2
3
adoriTagsService.setPlayer(player);
adoriTagsService.setAdoriMediaCodecAudioRendererFactory(
        adoriMediaCodecAudioRendererFactory);

2.3: Cleanup

When you want to close the player and stop using tag service, release tag service before releasing the player. See the below example.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
// Stop the player
player.stop();

// If you had setup any player event listeners, remove them
player.removeListener(your_player_event_listener);

// Release tags service
// Same instance of `AdoriTagsService` should not be used again after its released
adoriTagsService.release();
adoriTagsService = null;

// Release player
player.release();
player = null;
// ...

Step 3: Setup AdoriTagsView

AdoriTagsView is responsible for rendering the interactive experiences on the display.

3.1: Create tags view

Add AdoriTagsView to your layout xml file.

1
2
3
4
<com.adorilabs.sdk.ui.UI.AdoriTagsView
    android:id="@+id/tagsView"
    android:layout_width="match_parent"
    android:layout_height="match_parent"/>

You can configure the AdoriTagsView in your activity/fragment.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
AdoriTagsView adoriTagsView;

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    //Set the adoriTagsView to the tagsUI object
    adoriTagsView = findViewById(R.id.tagsView);
}

Tip

Specifying the real estate for Adori Tags View is important. We recommend a full-screen experience beginning at top of the screen and ending just above the audio player controls.

The recommended Width : Height ratio is 0.56 : 1.0

Example

Please see a reference screenshot below of an interactive tag experience from the IVM Android Podcast App that follows this recommended style guide.

3.2: On Resume

AdoriTagsView relies on the AdoriTagsService to retrieve and display the tags.

1
2
3
4
5
6
@Override
 public void onResume() {
    super.onResume();
    // Obtain the adoriTagsService instance and pass it to the adoriTagsView
    adoriTagsView.setTagService(adoriTagsService);
}

Tip

If you are using tag view inside custom views, use the lifecycle events of that view's fragment/activity to call setTagService.

3.3: On Pause

Release the tags view when your activity/fragment is paused.

1
2
3
4
5
@Override
public void onPause() {
    super.onPause();
    adoriTagsView.release();
}

Tip

If you are using tag view inside custom views, use the lifecycle events of that view's fragment/activity to call release.

Step 4: Setup AdoriSDKClient

Setup the Adori SDK client by passing the application component.

4.1: Setup

AdoriSDKClient needs instance of your application for initialization.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
import com.adorilabs.sdk.ui.AdoriSDKClient;

public class App extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
        AdoriSDKClient.setup(this);
    }
}  

4.2: Configuration

Use the adoriSDKClient to set user-specific configuration params.

1
2
3
AdoriSDKClient.setUserId("<uniqueUserId>");
AdoriSDKClient.setTagAlertNotification(<boolean>);
AdoriSDKClient.setTagNavigationOnPause(<boolean>);

UserID

UserId should be a unique and permanent id for a particular user across sessions and devices. Set this only after the mobile user logs in to the client app. Adori SDK uses this id to personalize tag views and interactions for each user.

UserId should be null or an empty string for logged out user.

TagNavigationOnPause

Adori's tag view already allows audio seeking based on tag navigation when the audio is playing. If this option is set to true, tag navigation and audio seeking is allowed even when the audio is paused.

TagAlertNotification

Adori SDK can play a faint notification sound along with the audio when a tag is visible on screen. This feature can be used to inform the user about the presence of an interactive experience. Your app may allow your users to set/unset this based on their personal preferences.

Step 5: Implement View Listener

Your app can keep track of all the user's interactions with Adori tags using AdoriTagsUIListener. Below example shows example implementation.

1
2
3
4
5
6
7
8
9
import com.adorilabs.sdk.ui.AdoriTagsUIListener;

//Implement AdoriTagsUIListener
public class PlayerActivity extends AppCompatActivity
    implements AdoriTagsUIListener {


    //Set listener to the adoriTagsView object after its initialized.
    adoriTagsView.setAdoriTagsUIListener(this);

5.1: Implement experienceInteracted

Your app may allow tags to be viewed anonymously without asking for users to login. But Adori SDK client requires unique id of the user to keep track of certain interactions and personalize tag views. Implement experienceInteracted to know when tag interactions need user id and prompt your user to log in.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
    // Override the experienceInteracted method to 
    // obtain the type of interaction made on the experience
    @Override
    public void experienceInteracted(
            Experience experience, 
            Boolean success, 
            @InteractionFailureReason int reason) {

        //Experience object indicates the experience that was interacted with.
        //Success param indicates if the interaction succeeded.
        //InteractionFailureReason param is an enum which indicates interaction failure cause.

        if (reason == InteractionFailureReason.NO_USER_ID) {
            tellUserLoginRequiredForThisInteractionAndshowTheLoginPopup();
            // Once the user logs in, use `AdoriSDKClient.setUserId` to 
            // pass the logged in user's id to Adori SDK.
        }
    }

Tip

When the experienceInteracted is called, your app should promp the user to login. Once the user logs in, use AdoriSDKClient.setUserId set the user's unique ID. This id should remain the same for that user across devices and platform.

5.2: Implement viewInteracted

This step is OPTIONAL. viewInteracted is called when the user navigates between tags using Adori tag view's navigation controls.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
    // Override the viewInteracted method to 
    // obtain the type of interaction made on the tagsView
    @Override
    public void viewInteracted(
            Boolean success, 
            @TagNavigationDirection int direction, 
            @InteractionFailureReason int reason) {

        //Success param indicates if the interaction succeeded.
        //TagNavigationDirection param indicates whether the view was swiped/tapped right or left.
        //InteractionFailureReason param is an enum which indicates interaction failure cause.

        if (!success && reason == InteractionFailureReason.AUDIO_PAUSED) {
            showSnackBar("This action is not available when audio is paused");
        }
    }
}

Next Steps