Popin Android SDK v2 – Integration Documentation

A video calling SDK for Android that enables seamless video communication with queue management, scheduling, and real-time notifications.

Requirements

• Min SDK: 24 (Android 7.0)

• Target SDK: 35 (Android 15)

• Java: 17

---

Integration

Step 1: Add JitPack Repository

settings.gradle.kts

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven {
            url = uri("https://jitpack.io")
            credentials { username = "YOUR_JITPACK_TOKEN" }
        }
    }
}

settings.gradle (Groovy)

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven {
            url 'https://jitpack.io'
            credentials { username authToken }
        }
    }
}

Store the token securely in local.properties (do not commit this file):

authToken=YOUR_JITPACK_TOKEN

Then load it in your root build.gradle:

Properties localProps = new Properties()
localProps.load(new FileInputStream(rootProject.file("local.properties")))
ext.authToken = localProps['authToken'] ?: ""

Step 2: Add the Dependency

dependencies {
    // Replace 'Tag' with the latest release version (e.g. 2.0.41)
    implementation 'com.github.Springr-Creatives.PopinAndroidSDK:PopinCustomerSDK:Tag'
}

Step 3: Configure AndroidManifest.xml

<application ...>
    <meta-data
        android:name="to.popin.androidsdk.POPIN_TOKEN"
        android:value="YOUR_ACCESS_TOKEN" />
</application>

Step 4: Initialize and Use

import to.popin.androidsdk.Popin;
import to.popin.androidsdk.PopinConfig;
import to.popin.androidsdk.listeners.PopinInitListener;
import to.popin.androidsdk.listeners.PopinEventsListener;
import to.popin.androidsdk.models.Product;

public class MainActivity extends AppCompatActivity {

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

        initPopin();
    }

    private void initPopin() {
        PopinConfig config = new PopinConfig.Builder()
            .userName("John Doe")
            .contactInfo("9876543210")
            .sandboxMode(true)
            .initListener(new PopinInitListener() {
                @Override
                public void onInitComplete(int userId) {
                    Log.d("Popin", "Ready, userId=" + userId);
                }

                @Override
                public void onInitFailed(String reason) {
                    Log.e("Popin", "Init failed: " + reason);
                }
            })
            .build();

        Popin.init(this, config);
    }

    public void onCallButtonClick(View view) {
        Popin.getInstance().startCall();
    }
}

---

Setup

Configure AndroidManifest.xml

Add the POPIN_TOKEN metadata inside the <application> tag. You will receive this token from the Popin Dashboard or your administrator.

<application ...>

    <meta-data
        android:name="to.popin.androidsdk.POPIN_TOKEN"
        android:value="YOUR_ACCESS_TOKEN" />

</application>

Note: The SDK manages runtime permissions automatically. Make sure your app has internet access enabled.

---

Initialization

Initialize the SDK using PopinConfig. This is typically done in your Application class or the onCreate() method of your main Activity.

Import Statements

import to.popin.androidsdk.Popin;
import to.popin.androidsdk.PopinConfig;
import to.popin.androidsdk.listeners.PopinInitListener;
import to.popin.androidsdk.listeners.PopinEventsListener;
import to.popin.androidsdk.models.Product;

import java.util.HashMap;
import java.util.Map;

Step 1: Prepare Meta Data (Optional)

Map<String, String> meta = new HashMap<>();
meta.put("businessUnit", "BUY");
meta.put("tenantId", "INDIA_VIDEO_PLATFORM");

Step 2: Prepare Product Data (Optional)

Product product = new Product(
    "product_id_123",
    "Product Name",
    "https://example.com/image.png",
    "https://example.com/product_page",
    "Additional Info",
    "Description or Specs"
);

Step 3: Build the Configuration

PopinConfig config = new PopinConfig.Builder()
        .userName("User Name")
        .contactInfo("9876543210")
        .identifier("your_user_id")
        .sandboxMode(true)
        .persistenceMode(true)
        .debugMode(false)
        .enableIncomingCalls(false)
        .startWithVideoDisabled(false)
        .hideDisconnectButton(false)
        .hideScreenShareButton(true)
        .hideFlipCameraButton(false)
        .hideMuteVideoButton(false)
        .hideMuteAudioButton(false)
        .hideBackButton(false)
        .callerId("your_caller_id")
        .expertDesignation("Expert")
        .secondaryProductText("Additional product info")
        .product(product)
        .meta(meta)
        .initListener(new PopinInitListener() {

            @Override
            public void onInitComplete(int userId) {
                // SDK initialized successfully
            }

            @Override
            public void onInitFailed(String reason) {
                // Initialization failed
            }
        })
        .build();

Step 4: Initialize the SDK

Popin.init(this, config);

---

Configuration Options

User Information

Method	Description
userName(String)	User's display name
contactInfo(String)	User's phone number or email
callerId(String)	Custom caller identifier
identifier(String)	Unique identifier for the user in your system (e.g. user ID or email). Can also be set later using setIdentifier()

Environment

Method	Description	Default
sandboxMode(boolean)	Use sandbox server for testing	false
persistenceMode(boolean)	Reuse existing SDK instance across re-initializations	true
debugMode(boolean)	Enable verbose SDK logging	false
enableIncomingCalls(boolean)	Enable incoming calls via FCM	false
startWithVideoDisabled(boolean)	Start calls with camera disabled	false

UI Button Visibility

Method	Description	Default
hideDisconnectButton(boolean)	Hide disconnect button	false
hideScreenShareButton(boolean)	Hide screen share button	false
hideFlipCameraButton(boolean)	Hide camera flip button	false
hideMuteVideoButton(boolean)	Hide video mute button	false
hideMuteAudioButton(boolean)	Hide audio mute button	false
hideBackButton(boolean)	Hide back button	false

Product, Metadata & Labels

Method	Description
product(Product)	Product associated with the call
meta(Map<String, String>)	Custom metadata
expertDesignation(String)	Expert role label
secondaryProductText(String)	Additional product card text
initListener(PopinInitListener)	Initialization callbacks

Runtime Configuration Updates

You can update product, callerId, and meta before starting a call without reinitializing the SDK.

PopinConfig config = Popin.getInstance().getConfig();

config.setProduct(new Product(
    "NEW-SKU",
    "New Product",
    "https://example.com/new.jpg",
    "https://example.com/new",
    "Updated product",
    "$199.99"
));

config.setCallerId("new_caller_id");

Map<String, String> newMeta = new HashMap<>();
newMeta.put("source", "android_app");
newMeta.put("campaign", "winter_sale");

config.setMeta(newMeta);

Popin.getInstance().startCall();

Updating User Name and Contact Info

Popin.getInstance().updateUserInfo(
    "New Name",
    "[e-mail]"
);

Setting User Identifier After Init

Popin.getInstance().setIdentifier("user_12345");

---

Usage

Setting the Events Listener

Popin.getInstance().setPopinEventsListener(new PopinEventsListener() {

    @Override
    public void onPermissionGiven() {
    }

    @Override
    public void onPermissionDenied() {
    }

    @Override
    public void onCallStart(int callId) {
    }

    @Override
    public void onCallCancel() {
    }

    @Override
    public void onQueuePositionChanged(int position) {
    }

    @Override
    public void onCallMissed() {
    }

    @Override
    public void onCallNetworkFailure(String participant) {
    }

    @Override
    public void onCallConnected() {
    }

    @Override
    public void onCallFailed() {
    }

    @Override
    public void onCallEnd() {
    }

    @Override
    public void onPipStateChanged(boolean isInPipMode) {
    }
});

Starting a Video Call

Popin.getInstance().startCall();

Cancelling a Call

Popin.getInstance().cancelCall();

Logging Out / Deinitializing the SDK

Popin.deinit();

Note: After calling deinit(), Popin.getInstance() will throw until Popin.init() is called again.

---

Scheduling a Call

Get Available Schedule Slots

import to.popin.androidsdk.listeners.PopinScheduleListener;

Popin.getInstance().getAvailableScheduleSlots(
    new PopinScheduleListener() {

        @Override
        public void onAvailableScheduleLoaded(
                List<ScheduleSlotsModel.ScheduleSlot> slots) {
        }

        @Override
        public void onScheduleLoadError() {
        }
    }
);

Create a Scheduled Call

import to.popin.androidsdk.listeners.PopinCreateScheduleListener;

Popin.getInstance().createSchedule(
    "2024-01-15T10:00:00Z",
    new PopinCreateScheduleListener() {

        @Override
        public void onScheduleCreated() {
        }

        @Override
        public void onScheduleLoadError() {
        }
    }
);

---

Setting a User Group

import to.popin.androidsdk.listeners.PopinSetGroupListener;

Popin.getInstance().setGroup(
    "your_group_identifier",
    new PopinSetGroupListener() {

        @Override
        public void onSuccess() {
        }

        @Override
        public void onFailed(String reason) {
        }
    }
);

---

Inviting Participants

import to.popin.androidsdk.listeners.PopinInviteListener;

Popin.getInstance().inviteParticipant(
    callId,
    new PopinInviteListener() {

        @Override
        public void onInviteSuccess(String inviteUrl) {
        }

        @Override
        public void onInviteFailed(String reason) {
        }
    }
);

---

Receiving Incoming Calls via FCM

Important: For incoming calls to work, Popin.init() must be called in your Application class.

Required Permission

<uses-permission
    android:name="android.permission.USE_FULL_SCREEN_INTENT" />

Application Initialization

public class MyApplication extends Application {

    @Override
    public void onCreate() {
        super.onCreate();

        PopinConfig config = new PopinConfig.Builder()
            .userName("User Name")
            .contactInfo("9876543210")
            .enableIncomingCalls(true)
            .build();

        Popin.init(this, config);
    }
}

Register in AndroidManifest.xml:

<application
    android:name=".MyApplication"
    ... >

Enable incoming calls:

PopinConfig config = new PopinConfig.Builder()
    .enableIncomingCalls(true)
    .build();

Forward the FCM Token

public class MyFirebaseMessagingService
        extends FirebaseMessagingService {

    @Override
    public void onNewToken(String token) {
        super.onNewToken(token);
        Popin.setFcmToken(getApplicationContext(), token);
    }
}

Forward Incoming Call Messages

public class MyFirebaseMessagingService
        extends FirebaseMessagingService {

    @Override
    public void onNewToken(String token) {
        super.onNewToken(token);
        Popin.setFcmToken(getApplicationContext(), token);
    }

    @Override
    public void onMessageReceived(RemoteMessage remoteMessage) {
        super.onMessageReceived(remoteMessage);

        if (Popin.onFcmMessageReceived(
                remoteMessage.getData())) {
            return;
        }

        // Handle your own messages here
    }
}

Note: Popin messages contain "source": "popin" in the data payload.

Call Accepted Callback (Optional)

import to.popin.androidsdk.listeners.PopinCallAcceptedListener;

@Override
public void onMessageReceived(RemoteMessage remoteMessage) {
    super.onMessageReceived(remoteMessage);

    boolean handled =
            Popin.onFcmMessageReceived(
                    remoteMessage.getData(),
                    callId -> Log.d(
                            "Popin",
                            "Call " + callId + " accepted"
                    )
            );

    if (handled) return;

    // Handle your own messages here
}

Method	Description
onCallAccepted(int callId)	Called when an incoming call is accepted

FCM Flow

![FCM Flow Diagram](docs/fcm_flow.png)

---

Event Listeners Reference

PopinInitListener

Method	Description
onInitComplete(int userId)	SDK initialized and ready
onInitFailed(String reason)	Initialization failed

PopinEventsListener

Method	Description
onPermissionGiven()	Permissions granted
onPermissionDenied()	Permissions denied
onCallStart(int callId)	Call started and queued
onCallCancel()	Call cancelled
onQueuePositionChanged(int position)	Queue position updated
onCallMissed()	Call missed
onCallNetworkFailure(String participant)	Network issue detected
onCallConnected()	Call connected
onCallFailed()	Call failed
onCallEnd()	Call ended
onPipStateChanged(boolean isInPipMode)	PiP mode changed

PopinScheduleListener

Method	Description
onAvailableScheduleLoaded(List<ScheduleSlot>)	Schedule slots loaded
onScheduleLoadError()	Failed to load slots

PopinCreateScheduleListener

Method	Description
onScheduleCreated()	Schedule created
onScheduleLoadError()	Failed to create schedule

PopinInviteListener

Method	Description
onInviteSuccess(String inviteUrl)	Invite URL generated
onInviteFailed(String reason)	Invite generation failed

PopinSetGroupListener

Method	Description
onSuccess()	Group assigned successfully
onFailed(String reason)	Failed to assign group

---

Permissions

The SDK automatically requests the following permissions at runtime:

Permission	Purpose
INTERNET	Network communication
CAMERA	Video capture
RECORD_AUDIO	Audio capture
MODIFY_AUDIO_SETTINGS	Audio routing
ACCESS_NETWORK_STATE	Network status
BLUETOOTH_CONNECT	Bluetooth audio (Android 12+)

---

ProGuard Configuration

The SDK ships consumer ProGuard rules in both PopinCustomerSDK and PopinCommonSDK. These rules are merged automatically into your release build when using the AAR.

No manual ProGuard configuration is required.

---

Environment Configuration

Production

PopinConfig config = new PopinConfig.Builder()
    .sandboxMode(false)
    .build();

Sandbox (Testing)

PopinConfig config = new PopinConfig.Builder()
    .sandboxMode(true)
    .build();