Migration Guide

Introduction

This migration guide outlines the changes required to transition from the legacy SpotIm SDK(1.X.Xv) to the new OpenWeb Android SDK(2.0.0v). The new API has been modularized for better clarity, maintainability, and customization.

This document provides a mapping of old API calls to the new ones, along with detailed migration steps and examples.

High-Level Changes

Some high-level changes introduced in this new API are:

Modular structure: The new API is divided into logical components like OWAnalytics, OWAuthentication, OWHelpers, and UIViews.
Improved customization: Enhanced options for analytics, authentication, and UI customization.
Deprecated methods: Some old methods have been removed or replaced.
New features: New methods and interfaces have been introduced, including additional settings and enhanced flow actions.

Mapping Table

This table shows how the old API calls are mapped to their equivalents in the updated framework:

Old API Call	New API Call	Comments
`SpotIm.init(context, spotId)`	`OpenWeb.manager.setSpotId(spotId: String)`	Initialization moved to `OWManager`.
`SpotIm.startSSO(callback)`	`OWAuthentication.startSSO(callback)`	Part of `OWAuthentication`.
`SpotIm.ssoWithJwt(jwt, callback)`	`OWAuthentication.ssoWithJwt(jwt, callback)`	Grouped under `OWAuthentication`.
`SpotIm.completeSSO(codeB, callback)`	`OWAuthentication.completeSSO(codeB, callback)`	Grouped under `OWAuthentication`.
`SpotIm.getUserLoginStatus(callback)`	`OWAuthentication.getUserLoginStatus(callback)`	Authentication-related methods are modularized.
`SpotIm.logout(callback)`	`OWAuthentication.logout(callback)`	Logout functionality moved to `OWAuthentication`.
`SpotIm.setLoginDelegate()`	`OWAuthentication.setLoginDelegate(delegate)`	Moved under the `OWAuthentication` module.
`SpotIm.setAnalyticsEventDelegate(delegate)`	`OWAnalytics.setAnalyticsEventDelegate(delegate)`	Analytics functionality now under `OWAnalytics`.
`SpotIm.setCustomBIData(dataMap)`	`OWAnalytics.analyticAdditionalInfo.customBIData`	BI data functions moved to `OWAnalytics`.
`SpotIm.getConversationCounters()`	`OWHelpers.getConversationCounters(...)`	Helper methods grouped under `OWHelpers`.
`SpotIm.setCustomUIDelegate(customUIDelegate)`	`OWCustomizations.setCustomUIDelegate(customUIDelegate)`	Customization settings are modularized.
`SpotIm.getPreConversationFragment()`	`OWUIFlows.OWUIFlowFragment.getPreConversation(postId, settings, ...)`	Part of the UI customization in Flows.
`SpotIm.getConversationFragment()`	`OWUIFlows.OWUIFlowFragment.getConversation(postId, settings, ...)`	Fragment-related methods grouped under `UIViews`.
`SpotIm.getCommentThreadFragment()`	`OWUIFlows.OWUIFlowFragment.getCommentThread(...)`	Thread-specific methods grouped under `UIViews`.
`SpotIm.getCreateCommentFragment()`	`OWUIFlows.OWUIFlowFragment.getCommentCreation(...)`	Comment creation methods grouped under `UIViews`.
`SpotIm.getReportReasonsFragment()`	`OWUIFlows.OWUIFlowFragment.getReportReasons(...)`	Report reasons now handled by `UIViews`.
`SpotIm.setGiphyProvider(giphyProvider)`	`OWCustomizations.setGiphyProvider(giphyProvider)`	Giphy integration moved to customizations.
`SpotIm.setUseWhiteNavigationColor()`	`OWCustomizations.setUseWhiteNavigationColor()`	Handled by theme management in `OWThemeStyle`.
`SpotIm.setAccessoryViewProvider(viewProvider)`	`OWCustomizations.setAccessoryViewProvider(viewProvider)`	Modularized into customizations.
`SpotIm.setAdditionalConfigurations()`	`OWHelpers.setAdditionalConfigurations(configuration)`	Helper methods now centralized.
`SpotIm.setEnableLandscape()`	`OWHelpers.orientationEnforcement`	Orientation now managed by `OWOrientationEnforcement`.
`SpotIm.getEnableLandscape()`	`OWHelpers.orientationEnforcement`	Orientation now managed by `OWOrientationEnforcement`.
`SpotIm.getConversationIntent(context, ...)`	`OWUIFlows.OWUIFlowIntent.getConversation(postId, ...)`	Generates an intent for the conversation flow.
`SpotIm.getCommentThreadIntent(context, ...)`	`OWUIFlows.OWUIFlowIntent.getCommentThread(postId, ...)`	Generates an intent for comment threads.
`SpotIm.getCreateCommentIntent(context, ...)`	`OWUIFlows.OWUIFlowIntent.getCommentCreation(postId, ...)`	Generates an intent for creating a comment.
`SpotIm.getPreConversationFragmentIndependent`	`OWUIViews.getPreConversation(postId, ...)`	Equivalent fragment method.
`SpotIm.getConversationFragmentIndependent`	`OWUIViews.getConversation(postId, ...)`	Equivalent fragment method.
`SpotIm.getCommentCreationFragmentIndependent`	`OWUIViews.getCommentCreation(postId, ...)`	Equivalent fragment method.
`SpotIm.getReportReasonsFragmentIndependent`	`OWUIViews.getReportReasons(postId, ...)`	Equivalent fragment method.
`SpotIm.getButtonOnlyMode()`	Removed	Replaced by pre-conversation settings.
`SpotIm.setButtonOnlyMode()`	Removed	Replaced by pre-conversation settings.
`SpotIm.setEnableCreateCommentNewDesign()`	Removed	Replaced by `OWCommentCreationSettings`.
`SpotIm.getEnableCreateCommentNewDesign()`	Removed	Replaced by `OWCommentCreationSettings`.
`SpotIm.setSsoStartLoginFlowMode()`	Removed
`SpotIm.setGoogleAdsProvider()`	Removed
`SpotIm.getSsoStartLoginFlowMode()`	Removed
`SpotIm.getConversationIntentIndependent`	Removed

New APIs

The following APIs have been added:

New API Call	Description
`OWUIViews.getCommentThread()`	Retrieves a Comment Thread Fragment with configured options.

Migration Steps

The steps to migrate are listed below:

Update SDK Dependency: Replace the SpotIm SDK dependency with the new package in your build.gradle file.
Replace Initialization: Update your SpotIm.init() calls to use OpenWeb.manager.setSpotId(spotId: String).
Refactor Authentication:
- Replace startSSO, ssoWithJwt, and completeSSO calls with their equivalents under OWAuthentication.
- Update getUserLoginStatus and logout to use OWAuthentication.
Update Analytics:
- Move setAnalyticsEventDelegate and setCustomBIData calls to OWAnalytics.
Refactor UI Methods:
- Replace fragment and intent retrieval methods (getConversationFragment, getCommentThreadFragment, etc.) with the appropriate OWUIViews and OWUIFlows methods.
Update Helpers:
- Replace getConversationCounters calls with the new OWHelpers.getConversationCounters() method.

Example Code Changes

An example code change is shown below:

Before

SpotIm.init(context, "spotId")

SpotIm.getConversationFragment(
  conversationId = "conversationId",
  conversationOptions = conversationOptions,
  callback = object : SpotCallback<Fragment> {
    override fun onSuccess(response: Fragment) {
      // Use fragment
    }

    override fun onFailure(exception: SpotException) {
      // Handle exception
    }
  }
)

After

OpenWeb.manager.setSpotId("spotId")

OpenWeb.manager.ui.flows.fragments.getConversation(
  postId = "postId",
  articleSettings = OWArticleSettings(),
  additionalSettings = OWAdditionalSettings(),
  flowActionsCallback = null,
  callback = object : SpotCallback<Fragment> {
    override fun onSuccess(response: Fragment) {
      // Use fragment
    }

    override fun onFailure(exception: SpotException) {
      // Handle exception
    }
  }
)

The latest update introduces a cleaner and more modular approach to handling analytics, authentication, and UI elements. This migration guide provides a clear mapping and examples to help you transition smoothly.

If you encounter any issues during migration, refer to the OpenWeb SDK documentation or contact OpenWeb support.