Android SDK Reference

Comprehensive API reference for the Hood Android SDK, including initialization, analytics, push notifications, user management, customization, and events. Supports Android 8.0+ with Firebase Cloud Messaging integration.

Setup & debugging

These methods are a reference for integrating the Hood SDK into your app. For full setup instructions, see Android SDK Setup.

init()

Initializes the Hood SDK. This should be called during application startup in your Application class. The API key can be found in your Ocamba platform dashboard.

Key behaviors:

Must be called once during app startup
Configures analytics, push notifications, and other features based on builder settings
Automatically registers for FCM token and starts background services

// Basic initialization with API key
OcambaHoood.getBuilder().init("YOUR_API_KEY");

// Or use manifest based API key
OcambaHoood.getBuilder().init();

Parameters:

apiKey (String, optional): Your Hood API key. If not provided, reads from AndroidManifest.xml

Builder Configuration

Configure SDK features before initialization:

OcambaHoood.getBuilder()
    .push()                                    // Enable push notifications
    .analytics(true)                           // Enable analytics (default: true)
    .scheduledNotification(1)                  // Scheduled notifications every minute
    .scheduledNotification(1, "Title", "Description")  // Custom scheduled
    .getNotificationBuilder()
        .customActionButtons()                 // Custom action buttons
        .customLayout()                        // Custom notification layout
        .customTrack()                         // Custom tracking
    .init("YOUR_API_KEY");

Key behaviors:

Chain configuration methods before calling init()
Each builder method returns the builder for method chaining
Configuration is applied only when init() is called

User identity & properties

The Hood SDK automatically creates a unique user ID for each device. You can associate additional user properties and identifiers for better targeting and analytics.

setCustomerUserId()

Sets a unique customer identifier for the current user. This helps correlate user behavior across sessions and devices.

// Set customer ID after user login
OcambaHoood.getInstance().setCustomerUserId("user_123");

Parameters:

userId (String): Unique customer identifier

setPartnerKeyId()

Sets a partner/ad platform identifier for retargeting and attribution.

OcambaHoood.getInstance().setPartnerKeyId("partner_abc");

Parameters:

partnerId (String): Partner platform identifier

Analytics & tracking

Track custom events and user behavior for analytics and campaign targeting.

track()

Tracks a custom event with optional properties. Events are queued locally and sent to the server when sendTrack() is called.

Key behaviors:

Events are stored locally until
Supports single key-value pairs, Maps, or JSONObjects
Events with empty values are treated as deletions

// Single key-value tracking
OcambaHoood.getInstance().track("button_clicked", "signup");

// Map-based tracking
HashMap<String, Object> params = new HashMap<>();
params.put("product_id", "123");
params.put("price", 29.99);
params.put("currency", "USD");
OcambaHoood.getInstance().track(params);

// JSON-based tracking
JSONObject eventData = new JSONObject();
eventData.put("event_type", "purchase");
eventData.put("amount", 99.99);
OcambaHoood.getInstance().track(eventData);

// Remove event from server (set empty value and flush)
OcambaHoood.getInstance().track("old_event", "");
OcambaHoood.getInstance().sendTrack();

Parameters:

key (String): Event name or key
value (Object): Event value (String, Map, or JSONObject)

sendTrack()

Sends all queued tracking events to the server.

OcambaHoood.getInstance().sendTrack();

getTrack()

Retrieves locally stored tracking events.

// Get all tracked events
Map<String, Object> allEvents = OcambaHoood.getInstance().getTrack();

// Get specific event
Object eventValue = OcambaHoood.getInstance().getTrack("button_clicked");

Parameters:

key (String, optional): Specific event key to retrieve

Returns:

All events or specific event value

removeTrack()

Removes tracking events from local storage.

// Remove all events
OcambaHoood.getInstance().removeTrack();

// Remove specific event
OcambaHoood.getInstance().removeTrack("button_clicked");

Parameters:

key (String, optional): Specific event key to remove

sessionEvent()

Tracks a session-level event with optional custom data.

// Basic session event
OcambaHoood.getInstance().sessionEvent("install");

// Custom session event with JSON data
JSONObject data = new JSONObject();
data.put("screen_name", "Home");
data.put("session_duration", 300);
OcambaHoood.getInstance().customSessionEvent("screen_view", data);

Parameters:

eventName (String): Session event name
customData (JSONObject, optional): Additional event data

UTM Parameters

Set and manage UTM parameters for campaign attribution and analytics.

setUtm()

Sets a UTM parameter for campaign tracking.

Key behaviors:

Used for campaign attribution
Supports standard UTM parameters (source, medium, campaign, term, content)

// Set UTM parameters
OcambaHoood.getInstance().setUtm("source", "google");
OcambaHoood.getInstance().setUtm("medium", "cpc");
OcambaHoood.getInstance().setUtm("campaign", "summer_sale");
OcambaHoood.getInstance().setUtm("term", "mobile_app");
OcambaHoood.getInstance().setUtm("content", "banner_ad");

Parameters:

key (String): UTM parameter name
value (String): UTM parameter value

getUtm()

Retrieves a UTM parameter value.

String source = OcambaHoood.getInstance().getUtm("source");
String campaign = OcambaHoood.getInstance().getUtm("campaign");

Parameters:

key (String): UTM parameter name

Returns:

String: UTM parameter value, or null if not set

removeUtm()

Removes a UTM parameter.

OcambaHoood.getInstance().removeUtm("source");

Parameters:

key (String): UTM parameter name to remove

Push notifications

Manage push notification registration, permissions, and token handling.

push()

Enables push notification functionality. Must be called before init().

Key behaviors:

Registers for FCM token automatically
Handles notification display and click tracking
Requires Firebase Cloud Messaging setup
Supports custom notification handling via receivers

OcambaHoood.getBuilder().push().init();

getFcmToken()

Retrieves the current FCM token for the device.

String token = OcambaHoood.getInstance().getFcmToken();
if (token != null) {
    Log.d("Hood", "FCM Token: " + token);
}

Returns:

String: Current FCM token

askForPushNotifications()

Requests notification permission from the user (Android 13+).

Key behaviors:

Shows native permission dialog
Automatically handles permission result
Required for notifications on Android 13+ (API 33+)
Callback provides permission result

OcambaHoood.getInstance().askForPushNotifications(true, new OcambaHoood.PromptForPushNotificationPermissionCallback() {
    @Override
    public void notificationsPermission(boolean accepted) {
        if (accepted) {
            Log.i("Hood", "Push permission granted");
            // SDK will proceed with token registration
        } else {
            Log.w("Hood", "Push permission denied");
            // Consider showing in-app explanation or settings redirect
        }
    }
});

Parameters:

fallbackToSettings (boolean): In case permission is not enabled open settings
callback (PromptForPushNotificationPermissionCallback): Permission result callback

notificationsPermissionAllowed()

Notifies the SDK that notification permission was granted (for manual permission handling).

// Call this after user grants permission manually
OcambaHoood.getInstance().notificationsPermissionAllowed();

Notification events

Handle custom notification behavior by extending OcambaNotificationReceiver.

OcambaNotificationReceiver

Base class for handling Hood notification events. Override methods to customize notification behavior.

Key behaviors:

Provides callbacks for all notification lifecycle events
Handles both user notifications and Hood notifications
Supports custom notification layouts and actions
Manages notification tracking and analytics

public class MyNotificationReceiver extends OcambaNotificationReceiver {
    
    @Override
    public void ocambaNewToken(String token, Context context) {
        // Called when a new FCM token is generated
        Log.d("Hood", "New FCM token: " + token);
        // Forward to your backend if needed
    }
    
    @Override
    public void ocambaNotificationUser(RemoteMessage remoteMessage, Context context) {
        // Called for user's own FCM notifications (not Hood notifications)
        if (remoteMessage.getNotification() != null) {
            String title = remoteMessage.getNotification().getTitle();
            String body = remoteMessage.getNotification().getBody();
            Log.i("Hood", "User notification - Title: " + title + ", Body: " + body);
        }
    }
    
    @Override
    public void ocambaNotificationReceived(OcambaNotificationObject message, Context context) {
        // Called when a Hood notification is received
        Log.i("Hood", "Hood notification received: " + message.getObject());
        
        // For custom layout mode, build your own notification here
        showCustomNotification(context, message);
    }
    
    @Override
    public void ocambaNotificationClick(OcambaNotificationObject message, Context context) {
        // Called when user taps a Hood notification
        Log.i("Hood", "Hood notification clicked: " + message.getObject());
        
        // Default behavior opens browser; override for custom actions
        Intent intent = new Intent(context, MainActivity.class);
        intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
        context.startActivity(intent);
    }
    
    @Override
    public void ocambaNotificationDismissed(Context context) {
        // Called when user dismisses notification
        Log.i("Hood", "Notification dismissed");
    }
    
    @Override
    public void ocambaNotificationActionButtons(String action, Context context) {
        // Called when user taps an action button
        Log.i("Hood", "Action button clicked: " + action);
    }
    
    @Override
    public void ocambaNotificationCustomAction(String action, Context context) {
        // Called for custom notification actions
        Log.i("Hood", "Custom action: " + action);
    }
    
    @Override
    public void ocambaNotificationMultiMessageReceived(ArrayList multiMessageList, Context context) {
        // Called for multi-message notifications
        Log.i("Hood", "Multi-message received: " + multiMessageList.size() + " messages");
    }
    
    private void showCustomNotification(Context context, OcambaNotificationObject message) {
        // Implement custom notification display
        NotificationManager notificationManager = (NotificationManager) context.getSystemService(Context.NOTIFICATION_SERVICE);
        // Build and show custom notification
    }
}

Registration in AndroidManifest.xml:

<receiver android:name=".MyNotificationReceiver" 
          android:enabled="true" 
          android:exported="false">
    <intent-filter>
        <action android:name="YOUR_PACKAGE_NAME.OCAMBA_NOTIFICATION_CLICK"/>
        <action android:name="YOUR_PACKAGE_NAME.OCAMBA_NOTIFICATION_RECEIVED"/>
        <action android:name="YOUR_PACKAGE_NAME.OCAMBA_NOTIFICATION_TOKEN"/>
        <action android:name="YOUR_PACKAGE_NAME.OCAMBA_NOTIFICATION_USER"/>
        <action android:name="YOUR_PACKAGE_NAME.OCAMBA_NOTIFICATION_ACTION_BUTTONS"/>
        <action android:name="YOUR_PACKAGE_NAME.OCAMBA_NOTIFICATION_CUSTOM_ACTION"/>
        <action android:name="YOUR_PACKAGE_NAME.OCAMBA_NOTIFICATION_DISMISSED"/>
        <action android:name="YOUR_PACKAGE_NAME.OCAMBA_NOTIFICATION_MULTI_MESSAGE_RECEIVED"/>
    </intent-filter>
</receiver>

<!-- Map the SDK receiver -->
<meta-data android:name="com.ocamba.OcambaReceiver" 
           android:value="your.package.MyNotificationReceiver" />

Customization

Customize notification appearance, behavior, and tracking.

customActionButtons()

Enables custom action buttons for notifications.

Key behaviors:

Allows custom notification actions
Overrides default notification behavior
Requires custom receiver implementation

OcambaHoood.getBuilder().getNotificationBuilder().customActionButtons().init();

customLayout()

Enables custom notification layout.

Key behaviors:

Allows complete control over notification appearance
Requires custom receiver to build notifications
Overrides default notification display

OcambaHoood.getBuilder().getNotificationBuilder().customLayout().init();

customTrack()

Enables custom notification tracking.

Key behaviors:

Provides raw notification data for custom tracking
Allows custom impression and click tracking
Requires manual tracker implementation

OcambaHoood.getBuilder().getNotificationBuilder().customTrack().init();

Notification Resources

Customize notification appearance with resource files:

Notification Icon (res/drawable/ocamba_nc_icon.xml):

<vector xmlns:android="http://schemas.android.com/apk/res/android"
    android:width="24dp"
    android:height="24dp"
    android:viewportWidth="24"
    android:viewportHeight="24">
    <path android:fillColor="#FFFFFF"
          android:pathData="M12,2C6.48,2 2,6.48 2,12s4.48,10 10,10 10,-4.48 10,-10S17.52,2 12,2z"/>
</vector>

Notification Colors (res/values/colors.xml):

<color name="ocamba_nc_name_color">#006291</color>
<color name="ocamba_nc_text_color">#006291</color>
<color name="ocamba_nc_title_color">#DB0000</color>

Multimessage Indicators:

res/drawable/ocamba_multimessage_indicator.xml
res/drawable/ocamba_multimessage_arrow_next.xml
res/drawable/ocamba_multimessage_arrow_previous.xml

Scheduled notifications

Show periodic local notifications to increase user engagement.

scheduledNotification()

Schedules periodic local notifications.

Key behaviors:

Creates local notifications (not server-sent)
Uses default or custom notification content
Respects system notification settings

// Default notification every minute
OcambaHoood.getBuilder().scheduledNotification(1).init();

// Custom notification every minute
OcambaHoood.getBuilder().scheduledNotification(
    1, 
    "Check back!", 
    "We have new content for you"
).init();

Parameters:

intervalMs (long): Notification interval in minutes
title (String, optional): Custom notification title
description (String, optional): Custom notification description

Advanced tracking

Implement custom impression and click tracking for detailed analytics.

getTracker()

Sends tracking requests to Hood servers for impression and click events.

Key behaviors:

Used with customTrack() mode
Provides detailed tracking for custom notifications
Returns tracking confirmation

// Send impression tracker
OcambaRequest.getInstance().getTracker(message.getImpTracker(), new OcambaResponseCallback() {
    @Override
    public void onFailure(Exception e) {
        Log.e("Hood", "Impression tracker failed", e);
    }
    
    @Override
    public void onResponse(int code, String response) {
        Log.i("Hood", "Impression tracked successfully: " + response);
    }
});

// Send click tracker
OcambaRequest.getInstance().getTracker(message.getClickTracker(), new OcambaResponseCallback() {
    @Override
    public void onFailure(Exception e) {
        Log.e("Hood", "Click tracker failed", e);
    }
    
    @Override
    public void onResponse(int code, String response) {
        Log.i("Hood", "Click tracked successfully: " + response);
    }
});

Parameters:

trackerUrl (String): Tracker URL from notification object
callback (OcambaResponseCallback): Response callback

Troubleshooting

SDK Initialization Failed
- Verify API key is correct and active
- Check internet connectivity
- Ensure Firebase is properly configured
- Verify google-services.json is in app directory
Push Notifications Not Working
- Confirm FCM API is enabled in Google Cloud Console
- Check POST_NOTIFICATIONS permission on Android 13+
- Verify device has Google Play Services
- Test on physical device (emulators may be unreliable)
Analytics Not Tracking
- Ensure analytics is enabled: .analytics(true)
- Check that sendTrack() is called
- Verify internet connectivity
- Review logcat for SDK errors
Custom Receiver Not Working
- Verify receiver is registered in AndroidManifest.xml
- Check package name in intent filters
- Ensure receiver extends OcambaNotificationReceiver
- Verify <meta-data> mapping is correct

Debug Tips

Enable debug logging in your app
Check Firebase Console for FCM token registration
Use Android Studio’s logcat to monitor SDK logs
Test with different Android versions and devices
Verify notification channels are created (Android 8+)

Need Help?

Contact support at [email protected] with:

Your App ID
Android version and device information
Relevant logs or error messages
Steps to reproduce the issue

Get Started

Android SDK Reference

Android SDK Reference

Setup & debugging

init()

Builder Configuration

User identity & properties

setCustomerUserId()

setPartnerKeyId()

Analytics & tracking

track()

sendTrack()

getTrack()

removeTrack()

sessionEvent()

UTM Parameters

setUtm()

getUtm()

removeUtm()

Push notifications

push()

getFcmToken()

askForPushNotifications()

notificationsPermissionAllowed()

Notification events

OcambaNotificationReceiver

Customization

customActionButtons()

customLayout()

customTrack()

Notification Resources

Scheduled notifications

scheduledNotification()

Advanced tracking

getTracker()

Troubleshooting

Debug Tips

Need Help?