(Previous: SDK Modules)
All the steps in this page are mandatory for succesful 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.
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
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>); |
Variable Definitions
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 |
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 (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 up: Sample App