Package com.swrve.sdk

Class SwrveSDKBase

  • Direct Known Subclasses:
    SwrveSDK

    public abstract class SwrveSDKBase
    extends java.lang.Object
    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected static ISwrveBase instance  
    • Constructor Summary

      Constructors 
      Constructor Description
      SwrveSDKBase()  
    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      protected static void checkInstanceCreated()  
      static void currencyGiven​(java.lang.String givenCurrency, double givenAmount)
      Add a Swrve.currency_given event to the event queue.
      static void embeddedControlMessageImpressionEvent​(SwrveEmbeddedMessage message)
      Send impression event for an embedded control campaign
      static void embeddedMessageButtonWasPressed​(SwrveEmbeddedMessage message, java.lang.String buttonName)
      Process an embedded message engagement event.
      static void embeddedMessageWasShownToUser​(SwrveEmbeddedMessage message)
      Inform that an embedded message has been served and processed.
      static void event​(java.lang.String name)
      Add a generic named event to the event queue.
      static void event​(java.lang.String name, java.util.Map<java.lang.String,​java.lang.String> payload)
      Add a generic named event to the event queue.
      static void flushToDisk()
      Flush events and others to the device's disk.
      static java.lang.String getApiKey()
      Get the current api key
      static java.lang.String getAppStoreURLForApp​(int appId)
      Get app store link configured in the dashboard for a given app id.
      static java.io.File getCacheDir()
      Get location of the chosen cache folder where the resources will be downloaded.
      static org.json.JSONObject getDeviceInfo()
      Collect device information
      static java.lang.String getExternalUserId()
      Get the current external user id.
      static java.util.Date getInitialisedTime()
      Get the time when the SDK was initialized.
      static ISwrveBase getInstance()  
      static java.lang.String getLanguage()
      Get the current language
      static SwrveBaseCampaign getMessageCenterCampaign​(int campaignId, java.util.Map<java.lang.String,​java.lang.String> properties)
      Get the active MessageCenter campaign targeted for this user.
      static java.util.List<SwrveBaseCampaign> getMessageCenterCampaigns()
      Get the list active MessageCenter campaigns targeted for this user.
      static java.util.List<SwrveBaseCampaign> getMessageCenterCampaigns​(com.swrve.sdk.messaging.SwrveOrientation orientation)
      Get the list active MessageCenter campaigns targeted for this user.
      static java.util.List<SwrveBaseCampaign> getMessageCenterCampaigns​(com.swrve.sdk.messaging.SwrveOrientation orientation, java.util.Map<java.lang.String,​java.lang.String> properties)
      Get the list active MessageCenter campaigns targeted for this user.
      static java.util.List<SwrveBaseCampaign> getMessageCenterCampaigns​(java.util.Map<java.lang.String,​java.lang.String> properties)
      Get the list active MessageCenter campaigns targeted for this user.
      static java.lang.String getPersonalizedEmbeddedMessageData​(SwrveEmbeddedMessage message, java.util.Map<java.lang.String,​java.lang.String> personalizationProperties)
      Get the personalized data string from a SwrveEmbeddedMessage campaign with a map of custom personalization properties.
      static java.lang.String getPersonalizedText​(java.lang.String text, java.util.Map<java.lang.String,​java.lang.String> personalizationProperties)
      Get the personalized data string from a piece of text with a map of custom personalization properties.
      static void getRealTimeUserProperties​(SwrveRealTimeUserPropertiesListener listener)
      Request the list of real time user properties which have been retrieved along with Campaign and Resources for this user.
      static SwrveResourceManager getResourceManager()
      Get the SwrveResourceManager, which can be queried for up-to-date resource attribute values
      static java.lang.String getUserId()
      Get the current user id
      static void getUserResources​(SwrveUserResourcesListener listener)
      Request the list of resources for the user with full attribute data after any applicable AB Tests have been applied.
      static void getUserResourcesDiff​(SwrveUserResourcesDiffListener listener)
      Request all applicable AB-Tested resources for the user.
      static void handleDeeplink​(android.os.Bundle bundle)
      Handle a deeplink when the app is already installed i.e.
      static void handleDeferredDeeplink​(android.os.Bundle bundle)
      Handle a deeplink when the app was installed first from the play store` i.e.
      static void iap​(int quantity, java.lang.String productId, double productPrice, java.lang.String currency)
      Add a Swrve.iap event to the event queue.
      static void iap​(int quantity, java.lang.String productId, double productPrice, java.lang.String currency, SwrveIAPRewards rewards)
      Add a Swrve.iap event to the event queue.
      static void identify​(java.lang.String userId, SwrveIdentityResponse identityResponse)
      Identify users such that they can be tracked and targeted safely across multiple devices, platforms and channels.
      static boolean isStarted()
      Check if the SDK is started and currently tracking.
      static void markMessageCenterCampaignAsSeen​(SwrveBaseCampaign campaign)
      Mark this campaign as seen.
      static void purchase​(java.lang.String item, java.lang.String currency, int cost, int quantity)
      Add a Swrve.user_purchase event to the event queue.
      static void refreshCampaignsAndResources()
      Update campaign and resources values This function will be called automatically to keep campaigns and resources up-to-date.
      static void removeMessageCenterCampaign​(SwrveBaseCampaign campaign)
      Remove this campaign.
      static void sendQueuedEvents()
      Send events to Swrve servers.
      static void sessionStart()
      Add a Swrve.session.start event to the event queue.
      static void setCustomPayloadForConversationInput​(java.util.Map payload)
      Add a custom payload for user input events: Selecting a star-rating, Selecting a choice on a text questionnaire Selecting play on a video
      static void setLanguage​(java.util.Locale locale)
      Set the current language
      static void setResourcesListener​(SwrveResourcesListener resourcesListener)
      The resourcesListener onResourcesUpdated() method is invoked when user resources in the SwrveResourceManager have been initially loaded and each time user resources are updated.
      static boolean showMessageCenterCampaign​(SwrveBaseCampaign campaign)
      Display the given campaign without the need to trigger an event and skipping the configured rules.
      static boolean showMessageCenterCampaign​(SwrveBaseCampaign campaign, java.util.Map<java.lang.String,​java.lang.String> properties)
      Display the given campaign without the need to trigger an event and skipping the configured rules.
      static void shutdown()
      Shutdown the SDK.
      static void start​(android.app.Activity activity)
      Start the sdk if stopped or in SwrveInitMode.MANAGED mode.
      static void start​(android.app.Activity activity, java.lang.String userId)
      Start the sdk when in SwrveInitMode.MANAGED mode.
      static void stopTracking()
      Stop the SDK from tracking.
      static void userUpdate​(java.lang.String name, java.util.Date date)
      Add a single custom user property to the event queue specifying a date.
      static void userUpdate​(java.util.Map<java.lang.String,​java.lang.String> attributes)
      Add a group of custom user properties to the event queue.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

    • Constructor Detail

      • SwrveSDKBase

        public SwrveSDKBase()
    • Method Detail

      • identify

        public static void identify​(java.lang.String userId,
                                    SwrveIdentityResponse identityResponse)
        Identify users such that they can be tracked and targeted safely across multiple devices, platforms and channels. Throws RunTimeException if called in SwrveInitMode.MANAGED mode.
         
         SwrveSDK.identify("12345", new SwrveIdentityResponse() {
              @Override
              public void onSuccess(String status, String swrveId) {
        
              }
        
              @Override
              public void onError(int responseCode, String errorMessage) {
                  // please note in the event of an error the tracked userId will not reflect correctly on the backend until this
                  // call completes successfully
              }
         });
         
         
        Parameters:
        userId - ID that uniquely identifies your user. Personal identifiable information should not be used. An error may be returned if such information is submitted as the userID eg email, phone number etc.
        identityResponse - Interface with onSuccess onError callbacks
      • handleDeeplink

        public static void handleDeeplink​(android.os.Bundle bundle)
        Handle a deeplink when the app is already installed i.e. using facebook API
         
         AppLinkData appLinkData = AppLinkData.createFromActivity(this);
                if (appLinkData != null) {
                    SwrveSDK.handleDeeplink(appLinkData.getArgumentBundle());
                }
         
         
        Parameters:
        bundle - the bundle to process
      • handleDeferredDeeplink

        public static void handleDeferredDeeplink​(android.os.Bundle bundle)
        Handle a deeplink when the app was installed first from the play store` i.e. using facebook API
         
         AppLinkData.fetchDeferredAppLinkData(this, new AppLinkData.CompletionHandler(){
        
             public void onDeferredAppLinkDataFetched(AppLinkData appLinkData) {
                  Bundle data = appLinkData.getArgumentBundle();
                  SwrveSDK.handleDeferredDeeplink(data);
              }
              });
         
         
        Parameters:
        bundle - the bundle to process
      • sessionStart

        public static void sessionStart()
        Add a Swrve.session.start event to the event queue. This event should typically be added in your main activity's onStart method.
      • event

        public static void event​(java.lang.String name)
        Add a generic named event to the event queue.
        Parameters:
        name - the name of the event in question. The character '.' is used as grouping syntax.
      • event

        public static void event​(java.lang.String name,
                                 java.util.Map<java.lang.String,​java.lang.String> payload)
        Add a generic named event to the event queue.
        Parameters:
        name - the name of the event in question. The character '.' is used as grouping syntax.
        payload - a dictionary of key-value pairs to be supplied with this named event. Typically this would be information about the event rather than about the user. Compare with the userUpdate function for properties of the user.
      • purchase

        public static void purchase​(java.lang.String item,
                                    java.lang.String currency,
                                    int cost,
                                    int quantity)
        Add a Swrve.user_purchase event to the event queue. This event should be added on virtual goods purchase in your app.
        Parameters:
        item - unique name of the purchased item
        currency - currency in Swrve to be used for this purchase. This currency must be declared in the Swrve dashboard before calling this function. If this currency is not declared this event will be rejected.
        cost - cost of the item in units of 'currency'
        quantity - number of the item purchased
      • currencyGiven

        public static void currencyGiven​(java.lang.String givenCurrency,
                                         double givenAmount)
        Add a Swrve.currency_given event to the event queue. This event should be added on award of virtual currency in the app.
        Parameters:
        givenCurrency - currency in Swrve to be used for this gift. This currency must be declared in the Swrve dashboard before calling this function. If this currency is not declared this event will be rejected.
        givenAmount - amount of currency given to the user.
      • userUpdate

        public static void userUpdate​(java.util.Map<java.lang.String,​java.lang.String> attributes)
        Add a group of custom user properties to the event queue. This event would typically be added to the queue after session_start and at points where properties of your users change - for example, levelUp.
        Parameters:
        attributes - key-value pairs of properties of the user. Typical values would be level = number, referrer = channel, coin balance = number.
      • userUpdate

        public static void userUpdate​(java.lang.String name,
                                      java.util.Date date)
        Add a single custom user property to the event queue specifying a date. This event would typically be added to the queue after session_start and at points where properties of your users change - for example, registration date or check-in date.
        Parameters:
        name - key for the custom user property
        date - date value for the custom user property
      • iap

        public static void iap​(int quantity,
                               java.lang.String productId,
                               double productPrice,
                               java.lang.String currency)
        Add a Swrve.iap event to the event queue. This event should be added for unvalidated real money transactions where a single item was purchased. (i.e where no in-app currency or bundle was purchased)
        Parameters:
        quantity - Quantity purchased. Must be greater than zero.
        productId - Unique product identifier for the item bought. This should match the Swrve resource name. Required, cannot be empty.
        productPrice - The price (in real money) of the product that was purchased. Note: this is not the price of the total transaction, but the per-product price. Must be greater than or equal to zero.
        currency - real world currency used for this transaction. This must be an ISO currency code. A typical value would be "USD". Required, cannot be empty.
      • iap

        public static void iap​(int quantity,
                               java.lang.String productId,
                               double productPrice,
                               java.lang.String currency,
                               SwrveIAPRewards rewards)
        Add a Swrve.iap event to the event queue. This event should be added for unvalidated real money transactions where in-app currency was purchased or where multiple items and/or currencies were purchased.

        To create the rewards object, create an instance of SwrveIAPRewards and use addItem() and addCurrency() to add the individual rewards

        Parameters:
        quantity - Quantity purchased. Must be greater than zero.
        productId - Unique product identifier for the item bought. This should match the Swrve resource name. Required, cannot be empty.
        productPrice - price of the product in real money. Note that this is the price per product, not the total price of the transaction (when quantity greater than 1) A typical value would be 0.99. Must be greater than or equal to zero.
        currency - real world currency used for this transaction. This must be an ISO currency code. A typical value would be "USD". Required, cannot be empty.
        rewards - SwrveIAPRewards object containing any in-app currency and/or additional items included in this purchase that need to be recorded.
      • getResourceManager

        public static SwrveResourceManager getResourceManager()
        Get the SwrveResourceManager, which can be queried for up-to-date resource attribute values
        Returns:
        resource manager
      • setResourcesListener

        public static void setResourcesListener​(SwrveResourcesListener resourcesListener)
        The resourcesListener onResourcesUpdated() method is invoked when user resources in the SwrveResourceManager have been initially loaded and each time user resources are updated.
        Parameters:
        resourcesListener - Resource listener
      • getUserResources

        public static void getUserResources​(SwrveUserResourcesListener listener)
        Request the list of resources for the user with full attribute data after any applicable AB Tests have been applied. This request is executed on a background thread, which will call methods on the user-provided listener parameter.

        If no user id has been specified this function raises a NoUserIdSwrveException exception to the listener object.

        Parameters:
        listener - The custom listener
      • getUserResourcesDiff

        public static void getUserResourcesDiff​(SwrveUserResourcesDiffListener listener)
        Request all applicable AB-Tested resources for the user. This request is executed on a background thread, which will call methods on the user-provided listener parameter.

        If no user id has been specified this function raises a NoUserIdSwrveException exception to the listener object.

        Parameters:
        listener - The custom listener
      • getRealTimeUserProperties

        public static void getRealTimeUserProperties​(SwrveRealTimeUserPropertiesListener listener)
        Request the list of real time user properties which have been retrieved along with Campaign and Resources for this user.

        Parameters:
        listener - The custom listener
      • sendQueuedEvents

        public static void sendQueuedEvents()
        Send events to Swrve servers.
      • flushToDisk

        public static void flushToDisk()
        Flush events and others to the device's disk.
      • shutdown

        public static void shutdown()
        Shutdown the SDK. This instance will be unusable after shutdown.

        Note: All the background jobs will try to stop when this happens.

      • stopTracking

        public static void stopTracking()
        Stop the SDK from tracking. The sdk will remain stopped until a start api is called.
      • setLanguage

        public static void setLanguage​(java.util.Locale locale)
        Set the current language
        Parameters:
        locale - Language locale to use.
      • getLanguage

        public static java.lang.String getLanguage()
        Get the current language
        Returns:
        current language
      • getApiKey

        public static java.lang.String getApiKey()
        Get the current api key
        Returns:
        current api key
      • getUserId

        public static java.lang.String getUserId()
        Get the current user id
        Returns:
        current user id
      • getDeviceInfo

        public static org.json.JSONObject getDeviceInfo()
                                                 throws org.json.JSONException
        Collect device information
        Returns:
        device information
        Throws:
        org.json.JSONException - If there's an error
      • refreshCampaignsAndResources

        public static void refreshCampaignsAndResources()
        Update campaign and resources values This function will be called automatically to keep campaigns and resources up-to-date. You should only call this function manually if you have changed the value of config.autoDownloadCampaignsAndResources to false.
      • embeddedMessageButtonWasPressed

        public static void embeddedMessageButtonWasPressed​(SwrveEmbeddedMessage message,
                                                           java.lang.String buttonName)
        Process an embedded message engagement event. This function should be called by your implementation to inform Swrve of a button event.
        Parameters:
        message - embedded message that has been processed
        buttonName - button that was pressed.
      • embeddedMessageWasShownToUser

        public static void embeddedMessageWasShownToUser​(SwrveEmbeddedMessage message)
        Inform that an embedded message has been served and processed. This function should be called by your implementation to update the campaign information and send the appropriate data to Swrve.
        Parameters:
        message - embedded message that has been processed
      • embeddedControlMessageImpressionEvent

        public static void embeddedControlMessageImpressionEvent​(SwrveEmbeddedMessage message)
        Send impression event for an embedded control campaign
        Parameters:
        message - embedded message that has been processed
      • getPersonalizedEmbeddedMessageData

        public static java.lang.String getPersonalizedEmbeddedMessageData​(SwrveEmbeddedMessage message,
                                                                          java.util.Map<java.lang.String,​java.lang.String> personalizationProperties)
        Get the personalized data string from a SwrveEmbeddedMessage campaign with a map of custom personalization properties.
        Parameters:
        message - Embedded message campaign to personalize
        personalizationProperties - Custom properties which are used for personalization.
        Returns:
        The data string with personalization properties applied. Null is returned if personalization fails with the custom properties passed in.
      • getPersonalizedText

        public static java.lang.String getPersonalizedText​(java.lang.String text,
                                                           java.util.Map<java.lang.String,​java.lang.String> personalizationProperties)
        Get the personalized data string from a piece of text with a map of custom personalization properties.
        Parameters:
        text - String value which will be personalized
        personalizationProperties - Custom properties which are used for personalization.
        Returns:
        The data string with personalization properties applied. Null is returned if personalization fails with the custom properties passed in.
      • getAppStoreURLForApp

        public static java.lang.String getAppStoreURLForApp​(int appId)
        Get app store link configured in the dashboard for a given app id.
        Parameters:
        appId - id of the app
        Returns:
        String App store link for the app
      • getCacheDir

        public static java.io.File getCacheDir()
        Get location of the chosen cache folder where the resources will be downloaded.
        Returns:
        File path to the chosen cache folder
      • getInitialisedTime

        public static java.util.Date getInitialisedTime()
        Get the time when the SDK was initialized.
        Returns:
        the time the SDK was initialized.
      • getMessageCenterCampaigns

        public static java.util.List<SwrveBaseCampaign> getMessageCenterCampaigns()
        Get the list active MessageCenter campaigns targeted for this user. It will exclude campaigns that have been deleted with the removeMessageCenterCampaign method and those that do not support the current orientation. To obtain all MessageCenter campaigns independent of their orientation support use the getMessageCenterCampaigns(SwrveOrientation.Both) method.
        Returns:
        list of active MessageCenter campaigns.
      • getMessageCenterCampaigns

        public static java.util.List<SwrveBaseCampaign> getMessageCenterCampaigns​(com.swrve.sdk.messaging.SwrveOrientation orientation)
        Get the list active MessageCenter campaigns targeted for this user. It will exclude campaigns that have been deleted with the removeMessageCenterCampaign method and those that do not support the given orientation.
        Parameters:
        orientation - Orientation which the messages have to support
        Returns:
        list of active MessageCenter campaigns.
      • getMessageCenterCampaigns

        public static java.util.List<SwrveBaseCampaign> getMessageCenterCampaigns​(java.util.Map<java.lang.String,​java.lang.String> properties)
        Get the list active MessageCenter campaigns targeted for this user. It will exclude campaigns that have been deleted with the removeMessageCenterCampaign method and those that do not support the current orientation.

        To obtain all MessageCenter campaigns independent of their orientation support use the getMessageCenterCampaigns(SwrveOrientation.Both) method.

        Parameters:
        properties - additional properties which can be used for IAM personalization.
        Returns:
        list of active MessageCenter campaigns.
      • getMessageCenterCampaigns

        public static java.util.List<SwrveBaseCampaign> getMessageCenterCampaigns​(com.swrve.sdk.messaging.SwrveOrientation orientation,
                                                                                  java.util.Map<java.lang.String,​java.lang.String> properties)
        Get the list active MessageCenter campaigns targeted for this user. It will exclude campaigns that have been deleted with the removeMessageCenterCampaign method and those that do not support the given orientation.
        Parameters:
        orientation - Orientation which the messages have to support
        properties - additional properties which can be used for IAM personalization.
        Returns:
        list of active MessageCenter campaigns.
      • getMessageCenterCampaign

        public static SwrveBaseCampaign getMessageCenterCampaign​(int campaignId,
                                                                 java.util.Map<java.lang.String,​java.lang.String> properties)
        Get the active MessageCenter campaign targeted for this user. It will exclude campaigns that have been deleted with the removeMessageCenterCampaign method and those that do not support the current orientation.
        Parameters:
        campaignId - the id of the campaign to get
        properties - additional properties which can be used for IAM personalization.
        Returns:
        The active MessageCenter campaign is returned if campaign id is valid. Returns null if the campaign id is invalid or campaign is not active.
      • showMessageCenterCampaign

        public static boolean showMessageCenterCampaign​(SwrveBaseCampaign campaign)
        Display the given campaign without the need to trigger an event and skipping the configured rules.
        Parameters:
        campaign - The campaign
        Returns:
        true if the campaign was displayed.
      • showMessageCenterCampaign

        public static boolean showMessageCenterCampaign​(SwrveBaseCampaign campaign,
                                                        java.util.Map<java.lang.String,​java.lang.String> properties)
        Display the given campaign without the need to trigger an event and skipping the configured rules.
        Parameters:
        campaign - The campaign
        properties - additional properties which can be used for IAM personalization.
        Returns:
        true if the campaign was displayed.
      • removeMessageCenterCampaign

        public static void removeMessageCenterCampaign​(SwrveBaseCampaign campaign)
        Remove this campaign. It won't be returned anymore by the 'getMessageCenterCampaigns' methods.
        Parameters:
        campaign - the campaign
      • markMessageCenterCampaignAsSeen

        public static void markMessageCenterCampaignAsSeen​(SwrveBaseCampaign campaign)
        Mark this campaign as seen. This is done automatically by Swrve but you can call this if you are rendering the messages on your own.
        Parameters:
        campaign - the campaign
      • checkInstanceCreated

        protected static void checkInstanceCreated()
                                            throws java.lang.RuntimeException
        Throws:
        java.lang.RuntimeException
      • getExternalUserId

        public static java.lang.String getExternalUserId()
        Get the current external user id.
        Returns:
        current external user id
      • setCustomPayloadForConversationInput

        public static void setCustomPayloadForConversationInput​(java.util.Map payload)
        Add a custom payload for user input events: Selecting a star-rating, Selecting a choice on a text questionnaire Selecting play on a video

        If key pair values added is greater than 5 or Keys added conflict with existing swrve internal keys then the custom payload will be rejected and not added for the event. A debug log error will be generated.

        Parameters:
        payload - Map with custom key pair values.
      • getInstance

        public static ISwrveBase getInstance()
      • start

        public static void start​(android.app.Activity activity)
        Start the sdk if stopped or in SwrveInitMode.MANAGED mode. Tracking will begin using the last user or an auto generated userId if the first time the sdk is started.
        Parameters:
        activity - Activity where the session was started.
      • start

        public static void start​(android.app.Activity activity,
                                 java.lang.String userId)
        Start the sdk when in SwrveInitMode.MANAGED mode. Tracking will begin using the userId passed in. Can be called multiple times to switch the current userId to something else. A new session is started if not already started or if is already started with different userId. The sdk will remain started until the createInstance is called again. Throws RunTimeException if called in SwrveInitMode.AUTO mode.
        Parameters:
        activity - Activity where the session was started.
        userId - User id to start sdk with.
      • isStarted

        public static boolean isStarted()
        Check if the SDK is started and currently tracking.
        Returns:
        true if sdk is not waiting to be started and hasn't been stopped using the stopTracking api.