Package org.matomo.java.tracking

Class MatomoRequest

java.lang.Object
org.matomo.java.tracking.MatomoRequest
Direct Known Subclasses:
PiwikRequest
public class MatomoRequest extends Object
A class that implements the Matomo Tracking HTTP API. These requests can be sent using MatomoTracker.
Author:
brettcsorba

  • Field Details

  • Constructor Details

    • MatomoRequest

      public MatomoRequest(int siteId, String actionUrl)
      Create a new request from the id of the site being tracked and the full url for the current action. This constructor also sets: 
       
 Required = true
 Visior Id = random 16 character hex string
 Random Value = random 20 character hex string
 API version = 1
 Response as Image = false
      Overwrite these values yourself as desired.
      Parameters:
      siteId - the id of the website we're tracking a visit/action for
      actionUrl - the full URL for the current action

  • Method Details

    • builder

      public static MatomoRequestBuilder builder()

    • getActionName

      @Nullable public String getActionName()
      Get the title of the action being tracked
      Returns:
      the title of the action being tracked

    • setActionName

      public void setActionName(String actionName)
      Set the title of the action being tracked. It is possible to use slashes / to set one or several categories for this action. For example, Help / Feedback will create the Action Feedback in the category Help.
      Parameters:
      actionName - the title of the action to set. A null value will remove this parameter

    • getActionTime

      @Nullable public Long getActionTime()
      Get the amount of time it took the server to generate this action, in milliseconds.
      Returns:
      the amount of time

    • setActionTime

      public void setActionTime(Long actionTime)
      Set the amount of time it took the server to generate this action, in milliseconds. This value is used to process the Page speed report Avg. generation time column in the Page URL and Page Title reports, as well as a site wide running average of the speed of your server.
      Parameters:
      actionTime - the amount of time to set. A null value will remove this parameter

    • getActionUrl

      @Nullable public URL getActionUrl()
      Deprecated.
      Please use getActionUrlAsString()
      Get the full URL for the current action.
      Returns:
      the full URL

    • getActionUrlAsString

      @Deprecated @Nullable public String getActionUrlAsString()
      Deprecated.
      Get the full URL for the current action.
      Returns:
      the full URL

    • setActionUrl

      @Deprecated public void setActionUrl(@NonNull @NonNull URL actionUrl)
      Deprecated.
      Please use setActionUrl(String)
      Set the full URL for the current action.
      Parameters:
      actionUrl - the full URL to set. A null value will remove this parameter

    • setActionUrl

      public void setActionUrl(String actionUrl)
      Set the full URL for the current action.
      Parameters:
      actionUrl - the full URL to set. A null value will remove this parameter

    • setActionUrlWithString

      @Deprecated public void setActionUrlWithString(String actionUrl)
      Deprecated.
      Please use setActionUrl(String)
      Set the full URL for the current action.
      Parameters:
      actionUrl - the full URL to set. A null value will remove this parameter

    • getApiVersion

      @Nullable public String getApiVersion()
      Get the api version
      Returns:
      the api version

    • setApiVersion

      public void setApiVersion(String apiVersion)
      Set the api version to use (currently always set to 1)
      Parameters:
      apiVersion - the api version to set. A null value will remove this parameter

    • getAuthToken

      @Nullable public String getAuthToken()
      Get the authorization key.
      Returns:
      the authorization key

    • setAuthToken

      public void setAuthToken(String authToken)
      Set the 32 character authorization key used to authenticate the API request.
      Parameters:
      authToken - the authorization key to set. A null value will remove this parameter

    • verifyAuthTokenSet

      public void verifyAuthTokenSet()
      Verifies that AuthToken has been set for this request. Will throw an IllegalStateException if not.

    • getCampaignKeyword

      @Nullable public String getCampaignKeyword()
      Get the campaign keyword
      Returns:
      the campaign keyword

    • setCampaignKeyword

      public void setCampaignKeyword(String campaignKeyword)
      Set the Campaign Keyword (see Tracking Campaigns). Used to populate the Referrers > Campaigns report (clicking on a campaign loads all keywords for this campaign). Note: this parameter will only be used for the first pageview of a visit.
      Parameters:
      campaignKeyword - the campaign keyword to set. A null value will remove this parameter

    • getCampaignName

      @Nullable public String getCampaignName()
      Get the campaign name
      Returns:
      the campaign name

    • setCampaignName

      public void setCampaignName(String campaignName)
      Set the Campaign Name (see Tracking Campaigns). Used to populate the Referrers > Campaigns report. Note: this parameter will only be used for the first pageview of a visit.
      Parameters:
      campaignName - the campaign name to set. A null value will remove this parameter

    • getCharacterSet

      @Nullable public Charset getCharacterSet()
      Get the charset of the page being tracked
      Returns:
      the charset

    • setCharacterSet

      public void setCharacterSet(Charset characterSet)
      The charset of the page being tracked. Specify the charset if the data you send to Matomo is encoded in a different character set than the default utf-8.
      Parameters:
      characterSet - the charset to set. A null value will remove this parameter

    • getContentInteraction

      @Nullable public String getContentInteraction()
      Get the name of the interaction with the content
      Returns:
      the name of the interaction

    • setContentInteraction

      public void setContentInteraction(String contentInteraction)
      Set the name of the interaction with the content. For instance a 'click'.
      Parameters:
      contentInteraction - the name of the interaction to set. A null value will remove this parameter

    • getContentName

      @Nullable public String getContentName()
      Get the name of the content
      Returns:
      the name

    • setContentName

      public void setContentName(String contentName)
      Set the name of the content. For instance 'Ad Foo Bar'.
      Parameters:
      contentName - the name to set. A null value will remove this parameter

    • getContentPiece

      @Nullable public String getContentPiece()
      Get the content piece.
      Returns:
      the content piece.

    • setContentPiece

      public void setContentPiece(String contentPiece)
      Set the actual content piece. For instance the path to an image, video, audio, any text.
      Parameters:
      contentPiece - the content piece to set. A null value will remove this parameter

    • getContentTarget

      @Nullable public URL getContentTarget()
      Get the content target
      Returns:
      the target

    • getContentTargetAsString

      @Nullable public String getContentTargetAsString()
      Get the content target
      Returns:
      the target

    • setContentTarget

      @Deprecated public void setContentTarget(@NonNull @NonNull URL contentTarget)
      Deprecated.
      Please use setContentTarget(String)
      Set the target of the content. For instance the URL of a landing page.
      Parameters:
      contentTarget - the target to set. A null value will remove this parameter

    • setContentTarget

      public void setContentTarget(String contentTarget)
      Set the target of the content. For instance the URL of a landing page.
      Parameters:
      contentTarget - the target to set. A null value will remove this parameter

    • setContentTargetWithString

      @Deprecated public void setContentTargetWithString(String contentTarget)
      Deprecated.
      Please use setContentTarget(String)
      Set the target of the content. For instance the URL of a landing page.
      Parameters:
      contentTarget - the target to set. A null value will remove this parameter

    • getCurrentHour

      @Nullable public Integer getCurrentHour()
      Get the current hour.
      Returns:
      the current hour

    • setCurrentHour

      public void setCurrentHour(Integer currentHour)
      Set the current hour (local time).
      Parameters:
      currentHour - the hour to set. A null value will remove this parameter

    • getCurrentMinute

      @Nullable public Integer getCurrentMinute()
      Get the current minute.
      Returns:
      the current minute

    • setCurrentMinute

      public void setCurrentMinute(Integer currentMinute)
      Set the current minute (local time).
      Parameters:
      currentMinute - the minute to set. A null value will remove this parameter

    • getCurrentSecond

      @Nullable public Integer getCurrentSecond()
      Get the current second
      Returns:
      the current second

    • setCurrentSecond

      public void setCurrentSecond(Integer currentSecond)
      Set the current second (local time).
      Parameters:
      currentSecond - the second to set. A null value will remove this parameter

    • getCustomAction

      @Nullable public Boolean getCustomAction()
      Get the custom action
      Returns:
      the custom action

    • setCustomAction

      public void setCustomAction(Boolean customAction)
      Set the custom action
      Parameters:
      customAction - the second to set. A null value will remove this parameter

    • getCustomTrackingParameter

      public List<Object> getCustomTrackingParameter(@NonNull @NonNull String key)
      Gets the list of objects currently stored at the specified custom tracking parameter. An empty list will be returned if there are no objects set at that key.
      Parameters:
      key - the key of the parameter whose list of objects to get. Cannot be null
      Returns:
      the list of objects currently stored at the specified key

    • setCustomTrackingParameter

      public <T> void setCustomTrackingParameter(@NonNull @NonNull String key, @Nullable T value)
      Set a custom tracking parameter whose toString() value will be sent to the Matomo server. These parameters are stored separately from named Matomo parameters, meaning it is not possible to overwrite or clear named Matomo parameters with this method. A custom parameter that has the same name as a named Matomo parameter will be sent in addition to that named parameter.
      Parameters:
      key - the parameter's key. Cannot be null
      value - the parameter's value. Removes the parameter if null

    • addCustomTrackingParameter

      public void addCustomTrackingParameter(@NonNull @NonNull String key, @NonNull @NonNull Object value)
      Add a custom tracking parameter to the specified key. This allows users to have multiple parameters with the same name and different values, commonly used during situations where list parameters are needed
      Parameters:
      key - the parameter's key. Cannot be null
      value - the parameter's value. Cannot be null

    • clearCustomTrackingParameter

      public void clearCustomTrackingParameter()
      Removes all custom tracking parameters

    • getDeviceResolution

      @Nullable public String getDeviceResolution()
      Get the resolution of the device
      Returns:
      the resolution

    • setDeviceResolution

      public void setDeviceResolution(String deviceResolution)
      Set the resolution of the device the visitor is using, eg 1280x1024.
      Parameters:
      deviceResolution - the resolution to set. A null value will remove this parameter

    • getDownloadUrl

      @Nullable public URL getDownloadUrl()
      Get the url of a file the user had downloaded
      Returns:
      the url

    • getDownloadUrlAsString

      @Nullable public String getDownloadUrlAsString()
      Get the url of a file the user had downloaded
      Returns:
      the url

    • setDownloadUrl

      @Deprecated public void setDownloadUrl(@NonNull @NonNull URL downloadUrl)
      Deprecated.
      Please use setDownloadUrl(String)
      Set the url of a file the user has downloaded. Used for tracking downloads. We recommend to also set the url parameter to this same value.
      Parameters:
      downloadUrl - the url to set. A null value will remove this parameter

    • setDownloadUrl

      public void setDownloadUrl(String downloadUrl)
      Set the url of a file the user has downloaded. Used for tracking downloads. We recommend to also set the url parameter to this same value.
      Parameters:
      downloadUrl - the url to set. A null value will remove this parameter

    • setDownloadUrlWithString

      @Deprecated public void setDownloadUrlWithString(String downloadUrl)
      Deprecated.
      Please use setDownloadUrl(String)
      Set the url of a file the user has downloaded. Used for tracking downloads. We recommend to also set the url parameter to this same value.
      Parameters:
      downloadUrl - the url to set. A null value will remove this parameter

    • enableEcommerce

      public void enableEcommerce()
      Sets idgoal=0 in the request to track an ecommerce interaction: cart update or an ecommerce order.

    • verifyEcommerceEnabled

      public void verifyEcommerceEnabled()
      Verifies that Ecommerce has been enabled for the request. Will throw an IllegalStateException if not.

    • verifyEcommerceState

      public void verifyEcommerceState()
      Verifies that Ecommerce has been enabled and that Ecommerce Id and Ecommerce Revenue have been set for the request. Will throw an IllegalStateException if not.

    • getEcommerceDiscount

      @Nullable public Double getEcommerceDiscount()
      Get the discount offered.
      Returns:
      the discount

    • setEcommerceDiscount

      public void setEcommerceDiscount(Double discount)
      Set the discount offered. Ecommerce must be enabled, and EcommerceId and EcommerceRevenue must first be set.
      Parameters:
      discount - the discount to set. A null value will remove this parameter

    • getEcommerceId

      @Nullable public String getEcommerceId()
      Get the id of this order.
      Returns:
      the id

    • setEcommerceId

      public void setEcommerceId(String id)
      Set the unique string identifier for the ecommerce order (required when tracking an ecommerce order). Ecommerce must be enabled.
      Parameters:
      id - the id to set. A null value will remove this parameter

    • getEcommerceItem

      @Nullable public EcommerceItem getEcommerceItem(int index)
      Get the EcommerceItem at the specified index
      Parameters:
      index - the index of the EcommerceItem to return
      Returns:
      the EcommerceItem at the specified index

    • addEcommerceItem

      public void addEcommerceItem(@NonNull @NonNull EcommerceItem item)
      Add an EcommerceItem to this order. Ecommerce must be enabled, and EcommerceId and EcommerceRevenue must first be set.
      Parameters:
      item - the EcommerceItem to add. Cannot be null

    • clearEcommerceItems

      public void clearEcommerceItems()
      Clears all EcommerceItem from this order.

    • getEcommerceLastOrderTimestamp

      @Nullable public Long getEcommerceLastOrderTimestamp()
      Get the timestamp of the customer's last ecommerce order
      Returns:
      the timestamp

    • setEcommerceLastOrderTimestamp

      public void setEcommerceLastOrderTimestamp(Long timestamp)
      Set the UNUX timestamp of this customer's last ecommerce order. This value is used to process the "Days since last order" report. Ecommerce must be enabled, and EcommerceId and EcommerceRevenue must first be set.
      Parameters:
      timestamp - the timestamp to set. A null value will remove this parameter

    • getEcommerceRevenue

      @Nullable public Double getEcommerceRevenue()
      Get the grand total of the ecommerce order.
      Returns:
      the grand total

    • setEcommerceRevenue

      public void setEcommerceRevenue(Double revenue)
      Set the grand total of the ecommerce order (required when tracking an ecommerce order). Ecommerce must be enabled.
      Parameters:
      revenue - the grand total to set. A null value will remove this parameter

    • getEcommerceShippingCost

      @Nullable public Double getEcommerceShippingCost()
      Get the shipping cost of the ecommerce order.
      Returns:
      the shipping cost

    • setEcommerceShippingCost

      public void setEcommerceShippingCost(Double shippingCost)
      Set the shipping cost of the ecommerce order. Ecommerce must be enabled, and EcommerceId and EcommerceRevenue must first be set.
      Parameters:
      shippingCost - the shipping cost to set. A null value will remove this parameter

    • getEcommerceSubtotal

      @Nullable public Double getEcommerceSubtotal()
      Get the subtotal of the ecommerce order; excludes shipping.
      Returns:
      the subtotal

    • setEcommerceSubtotal

      public void setEcommerceSubtotal(Double subtotal)
      Set the subtotal of the ecommerce order; excludes shipping. Ecommerce must be enabled and EcommerceId and EcommerceRevenue must first be set.
      Parameters:
      subtotal - the subtotal to set. A null value will remove this parameter

    • getEcommerceTax

      @Nullable public Double getEcommerceTax()
      Get the tax amount of the ecommerce order.
      Returns:
      the tax amount

    • setEcommerceTax

      public void setEcommerceTax(Double tax)
      Set the tax amount of the ecommerce order. Ecommerce must be enabled, and EcommerceId and EcommerceRevenue must first be set.
      Parameters:
      tax - the tax amount to set. A null value will remove this parameter

    • getEventAction

      @Nullable public String getEventAction()
      Get the event action.
      Returns:
      the event action

    • setEventAction

      public void setEventAction(String eventAction)
      Set the event action. Must not be empty. (eg. Play, Pause, Duration, Add Playlist, Downloaded, Clicked...).
      Parameters:
      eventAction - the event action to set. A null value will remove this parameter

    • getEventCategory

      @Nullable public String getEventCategory()
      Get the event category.
      Returns:
      the event category

    • setEventCategory

      public void setEventCategory(String eventCategory)
      Set the event category. Must not be empty. (eg. Videos, Music, Games...).
      Parameters:
      eventCategory - the event category to set. A null value will remove this parameter

    • getEventName

      @Nullable public String getEventName()
      Get the event name.
      Returns:
      the event name

    • setEventName

      public void setEventName(String eventName)
      Set the event name. (eg. a Movie name, or Song name, or File name...).
      Parameters:
      eventName - the event name to set. A null value will remove this parameter

    • getEventValue

      @Nullable public Number getEventValue()
      Get the event value.
      Returns:
      the event value

    • setEventValue

      public void setEventValue(Number eventValue)
      Set the event value. Must be a float or integer value (numeric), not a string.
      Parameters:
      eventValue - the event value to set. A null value will remove this parameter

    • getGoalId

      @Nullable public Integer getGoalId()
      Get the goal id
      Returns:
      the goal id

    • setGoalId

      public void setGoalId(Integer goalId)
      Set the goal id. If specified, the tracking request will trigger a conversion for the goal of the website being tracked with this id.
      Parameters:
      goalId - the goal id to set. A null value will remove this parameter

    • getGoalRevenue

      @Nullable public Double getGoalRevenue()
      Get the goal revenue.
      Returns:
      the goal revenue

    • setGoalRevenue

      public void setGoalRevenue(Double goalRevenue)
      Set a monetary value that was generated as revenue by this goal conversion. Only used if idgoal is specified in the request.
      Parameters:
      goalRevenue - the goal revenue to set. A null value will remove this parameter

    • getHeaderAcceptLanguage

      @Nullable public String getHeaderAcceptLanguage()
      Get the Accept-Language HTTP header
      Returns:
      the Accept-Language HTTP header

    • setHeaderAcceptLanguage

      public void setHeaderAcceptLanguage(String acceptLangage)
      Set an override value for the Accept-Language HTTP header field. This value is used to detect the visitor's country if GeoIP is not enabled.
      Parameters:
      acceptLangage - the Accept-Language HTTP header to set. A null value will remove this parameter

    • getHeaderUserAgent

      @Nullable public String getHeaderUserAgent()
      Get the User-Agent HTTP header
      Returns:
      the User-Agent HTTP header

    • setHeaderUserAgent

      public void setHeaderUserAgent(String userAgent)
      Set an override value for the User-Agent HTTP header field. The user agent is used to detect the operating system and browser used.
      Parameters:
      userAgent - the User-Agent HTTP header tos et

    • getNewVisit

      @Nullable public Boolean getNewVisit()
      Get if this request will force a new visit.
      Returns:
      true if this request will force a new visit

    • setNewVisit

      public void setNewVisit(Boolean newVisit)
      If set to true, will force a new visit to be created for this action.
      Parameters:
      newVisit - if this request will force a new visit

    • getOutlinkUrl

      @Nullable public URL getOutlinkUrl()
      Get the outlink url
      Returns:
      the outlink url

    • getOutlinkUrlAsString

      @Nullable public String getOutlinkUrlAsString()
      Get the outlink url
      Returns:
      the outlink url

    • setOutlinkUrl

      @Deprecated public void setOutlinkUrl(@NonNull @NonNull URL outlinkUrl)
      Deprecated.
      Please use setOutlinkUrl(String)
      Set an external URL the user has opened. Used for tracking outlink clicks. We recommend to also set the url parameter to this same value.
      Parameters:
      outlinkUrl - the outlink url to set. A null value will remove this parameter

    • setOutlinkUrl

      public void setOutlinkUrl(String outlinkUrl)
      Set an external URL the user has opened. Used for tracking outlink clicks. We recommend to also set the url parameter to this same value.
      Parameters:
      outlinkUrl - the outlink url to set. A null value will remove this parameter

    • setOutlinkUrlWithString

      @Deprecated public void setOutlinkUrlWithString(String outlinkUrl)
      Deprecated.
      Please use setOutlinkUrl(String)
      Set an external URL the user has opened. Used for tracking outlink clicks. We recommend to also set the url parameter to this same value.
      Parameters:
      outlinkUrl - the outlink url to set. A null value will remove this parameter

    • getPageCustomVariable

      @Nullable @Deprecated public String getPageCustomVariable(String key)
      Deprecated.
      Use the getPageCustomVariable(int) method instead.
      Get the page custom variable at the specified key.
      Parameters:
      key - the key of the variable to get
      Returns:
      the variable at the specified key, null if key is not present

    • getPageCustomVariable

      @Nullable public CustomVariable getPageCustomVariable(int index)
      Get the page custom variable at the specified index.
      Parameters:
      index - the index of the variable to get. Must be greater than 0
      Returns:
      the variable at the specified key, null if nothing at this index

    • setPageCustomVariable

      @Deprecated public void setPageCustomVariable(String key, String value)
      Deprecated.
      Use the setPageCustomVariable(CustomVariable, int) method instead.
      Set a page custom variable with the specified key and value at the first available index. All page custom variables with this key will be overwritten or deleted
      Parameters:
      key - the key of the variable to set
      value - the value of the variable to set at the specified key. A null value will remove this custom variable

    • setPageCustomVariable

      public void setPageCustomVariable(CustomVariable customVariable, int index)
      Set a page custom variable at the specified index.
      Parameters:
      customVariable - the CustomVariable to set. A null value will remove the CustomVariable at the specified index
      index - the index of he CustomVariable to set

    • getPluginDirector

      @Nullable public Boolean getPluginDirector()
      Check if the visitor has the Director plugin.
      Returns:
      true if visitor has the Director plugin

    • setPluginDirector

      public void setPluginDirector(Boolean director)
      Set if the visitor has the Director plugin.
      Parameters:
      director - true if the visitor has the Director plugin

    • getPluginFlash

      @Nullable public Boolean getPluginFlash()
      Check if the visitor has the Flash plugin.
      Returns:
      true if the visitor has the Flash plugin

    • setPluginFlash

      @Nullable public void setPluginFlash(Boolean flash)
      Set if the visitor has the Flash plugin.
      Parameters:
      flash - true if the visitor has the Flash plugin

    • getPluginGears

      @Nullable public Boolean getPluginGears()
      Check if the visitor has the Gears plugin.
      Returns:
      true if the visitor has the Gears plugin

    • setPluginGears

      public void setPluginGears(Boolean gears)
      Set if the visitor has the Gears plugin.
      Parameters:
      gears - true if the visitor has the Gears plugin

    • getPluginJava

      @Nullable public Boolean getPluginJava()
      Check if the visitor has the Java plugin.
      Returns:
      true if the visitor has the Java plugin

    • setPluginJava

      public void setPluginJava(Boolean java)
      Set if the visitor has the Java plugin.
      Parameters:
      java - true if the visitor has the Java plugin

    • getPluginPDF

      @Nullable public Boolean getPluginPDF()
      Check if the visitor has the PDF plugin.
      Returns:
      true if the visitor has the PDF plugin

    • setPluginPDF

      public void setPluginPDF(Boolean pdf)
      Set if the visitor has the PDF plugin.
      Parameters:
      pdf - true if the visitor has the PDF plugin

    • getPluginQuicktime

      @Nullable public Boolean getPluginQuicktime()
      Check if the visitor has the Quicktime plugin.
      Returns:
      true if the visitor has the Quicktime plugin

    • setPluginQuicktime

      public void setPluginQuicktime(Boolean quicktime)
      Set if the visitor has the Quicktime plugin.
      Parameters:
      quicktime - true if the visitor has the Quicktime plugin

    • getPluginRealPlayer

      @Nullable public Boolean getPluginRealPlayer()
      Check if the visitor has the RealPlayer plugin.
      Returns:
      true if the visitor has the RealPlayer plugin

    • setPluginRealPlayer

      public void setPluginRealPlayer(Boolean realPlayer)
      Set if the visitor has the RealPlayer plugin.
      Parameters:
      realPlayer - true if the visitor has the RealPlayer plugin

    • getPluginSilverlight

      @Nullable public Boolean getPluginSilverlight()
      Check if the visitor has the Silverlight plugin.
      Returns:
      true if the visitor has the Silverlight plugin

    • setPluginSilverlight

      public void setPluginSilverlight(Boolean silverlight)
      Set if the visitor has the Silverlight plugin.
      Parameters:
      silverlight - true if the visitor has the Silverlight plugin

    • getPluginWindowsMedia

      @Nullable public Boolean getPluginWindowsMedia()
      Check if the visitor has the Windows Media plugin.
      Returns:
      true if the visitor has the Windows Media plugin

    • setPluginWindowsMedia

      public void setPluginWindowsMedia(Boolean windowsMedia)
      Set if the visitor has the Windows Media plugin.
      Parameters:
      windowsMedia - true if the visitor has the Windows Media plugin

    • getRandomValue

      @Nullable public String getRandomValue()
      Get the random value for this request
      Returns:
      the random value

    • setRandomValue

      public void setRandomValue(String randomValue)
      Set a random value that is generated before each request. Using it helps avoid the tracking request being cached by the browser or a proxy.
      Parameters:
      randomValue - the random value to set. A null value will remove this parameter

    • getReferrerUrl

      @Nullable public URL getReferrerUrl()
      Get the referrer url
      Returns:
      the referrer url

    • getReferrerUrlAsString

      @Nullable public String getReferrerUrlAsString()
      Get the referrer url
      Returns:
      the referrer url

    • setReferrerUrl

      @Deprecated public void setReferrerUrl(@NonNull @NonNull URL referrerUrl)
      Deprecated.
      Please use setReferrerUrl(String)
      Set the full HTTP Referrer URL. This value is used to determine how someone got to your website (ie, through a website, search engine or campaign).
      Parameters:
      referrerUrl - the referrer url to set. A null value will remove this parameter

    • setReferrerUrl

      public void setReferrerUrl(String referrerUrl)
      Set the full HTTP Referrer URL. This value is used to determine how someone got to your website (ie, through a website, search engine or campaign).
      Parameters:
      referrerUrl - the referrer url to set. A null value will remove this parameter

    • setReferrerUrlWithString

      @Deprecated public void setReferrerUrlWithString(String referrerUrl)
      Deprecated.
      Please use setReferrerUrl(String)
      Set the full HTTP Referrer URL. This value is used to determine how someone got to your website (ie, through a website, search engine or campaign).
      Parameters:
      referrerUrl - the referrer url to set. A null value will remove this parameter

    • getRequestDatetime

      @Nullable public MatomoDate getRequestDatetime()
      Get the datetime of the request
      Returns:
      the datetime of the request

    • setRequestDatetime

      public void setRequestDatetime(MatomoDate datetime)
      Set the datetime of the request (normally the current time is used). This can be used to record visits and page views in the past. The datetime must be sent in UTC timezone. Note: if you record data in the past, you will need to force Matomo to re-process reports for the past dates. If you set the Request Datetime to a datetime older than four hours then Auth Token must be set. If you set Request Datetime with a datetime in the last four hours then you don't need to pass Auth Token.
      Parameters:
      datetime - the datetime of the request to set. A null value will remove this parameter

    • getRequired

      @Nullable public Boolean getRequired()
      Get if this request will be tracked.
      Returns:
      true if request will be tracked

    • setRequired

      public void setRequired(Boolean required)
      Set if this request will be tracked by the Matomo server.
      Parameters:
      required - true if request will be tracked

    • getResponseAsImage

      @Nullable public Boolean getResponseAsImage()
      Get if the response will be an image.
      Returns:
      true if the response will be an an image

    • setResponseAsImage

      public void setResponseAsImage(Boolean responseAsImage)
      Set if the response will be an image. If set to false, Matomo will respond with a HTTP 204 response code instead of a GIF image. This improves performance and can fix errors if images are not allowed to be obtained directly (eg Chrome Apps). Available since Matomo 2.10.0.
      Parameters:
      responseAsImage - true if the response will be an image

    • getSearchCategory

      @Nullable public String getSearchCategory()
      Get the search category
      Returns:
      the search category

    • setSearchCategory

      public void setSearchCategory(String searchCategory)
      Specify a search category with this parameter. SearchQuery must first be set.
      Parameters:
      searchCategory - the search category to set. A null value will remove this parameter

    • getSearchQuery

      @Nullable public String getSearchQuery()
      Get the search query.
      Returns:
      the search query

    • setSearchQuery

      public void setSearchQuery(String searchQuery)
      Set the search query. When specified, the request will not be tracked as a normal pageview but will instead be tracked as a Site Search request.
      Parameters:
      searchQuery - the search query to set. A null value will remove this parameter

    • getSearchResultsCount

      @Nullable public Long getSearchResultsCount()
      Get the search results count.
      Returns:
      the search results count

    • setSearchResultsCount

      public void setSearchResultsCount(Long searchResultsCount)
      We recommend to set the search count to the number of search results displayed on the results page. When keywords are tracked with Search Results Count=0 they will appear in the "No Result Search Keyword" report. SearchQuery must first be set.
      Parameters:
      searchResultsCount - the search results count to set. A null value will remove this parameter

    • getSiteId

      @Nullable public Integer getSiteId()
      Get the id of the website we're tracking.
      Returns:
      the id of the website

    • setSiteId

      public void setSiteId(Integer siteId)
      Set the ID of the website we're tracking a visit/action for.
      Parameters:
      siteId - the id of the website to set. A null value will remove this parameter

    • getTrackBotRequests

      @Nullable public Boolean getTrackBotRequests()
      Set if bot requests should be tracked
      Returns:
      true if bot requests should be tracked

    • setTrackBotRequests

      public void setTrackBotRequests(Boolean trackBotRequests)
      By default Matomo does not track bots. If you use the Tracking Java API, you may be interested in tracking bot requests. To enable Bot Tracking in Matomo, set Track Bot Requests to true.
      Parameters:
      trackBotRequests - true if bot requests should be tracked

    • getUserCustomVariable

      @Nullable @Deprecated public String getUserCustomVariable(String key)
      Deprecated.
      Use the getVisitCustomVariable(int) method instead.
      Get the visit custom variable at the specified key.
      Parameters:
      key - the key of the variable to get
      Returns:
      the variable at the specified key, null if key is not present

    • getVisitCustomVariable

      @Nullable public CustomVariable getVisitCustomVariable(int index)
      Get the visit custom variable at the specified index.
      Parameters:
      index - the index of the variable to get
      Returns:
      the variable at the specified index, null if nothing at this index

    • setUserCustomVariable

      @Deprecated public void setUserCustomVariable(String key, String value)
      Deprecated.
      Use the setVisitCustomVariable(CustomVariable, int) method instead.
      Set a visit custom variable with the specified key and value at the first available index. All visit custom variables with this key will be overwritten or deleted
      Parameters:
      key - the key of the variable to set
      value - the value of the variable to set at the specified key. A null value will remove this parameter

    • setVisitCustomVariable

      public void setVisitCustomVariable(CustomVariable customVariable, int index)
      Set a user custom variable at the specified key.
      Parameters:
      customVariable - the CustomVariable to set. A null value will remove the custom variable at the specified index
      index - the index to set the customVariable at.

    • getUserId

      @Nullable public String getUserId()
      Get the user id for this request.
      Returns:
      the user id

    • setUserId

      public void setUserId(String userId)
      Set the user id for this request. User id is any non empty unique string identifying the user (such as an email address or a username). To access this value, users must be logged-in in your system so you can fetch this user id from your system, and pass it to Matomo. The user id appears in the visitor log, the Visitor profile, and you can Segment reports for one or several user ids. When specified, the user id will be "enforced". This means that if there is no recent visit with this user id, a new one will be created. If a visit is found in the last 30 minutes with your specified user id, then the new action will be recorded to this existing visit.
      Parameters:
      userId - the user id to set. A null value will remove this parameter

    • getVisitorCity

      @Nullable public String getVisitorCity()
      Get the visitor's city.
      Returns:
      the visitor's city

    • setVisitorCity

      public void setVisitorCity(String city)
      Set an override value for the city. The name of the city the visitor is located in, eg, Tokyo. AuthToken must first be set.
      Parameters:
      city - the visitor's city to set. A null value will remove this parameter

    • getVisitorCountry

      @Nullable public MatomoLocale getVisitorCountry()
      Get the visitor's country.
      Returns:
      the visitor's country

    • setVisitorCountry

      public void setVisitorCountry(MatomoLocale country)
      Set an override value for the country. AuthToken must first be set.
      Parameters:
      country - the visitor's country to set. A null value will remove this parameter

    • getVisitorCustomId

      @Nullable public String getVisitorCustomId()
      Get the visitor's custom id.
      Returns:
      the visitor's custom id

    • setVisitorCustomId

      public void setVisitorCustomId(String visitorCustomId)
      Set a custom visitor ID for this request. You must set this value to exactly a 16 character hexadecimal string (containing only characters 01234567890abcdefABCDEF). We recommended to set the UserId rather than the VisitorCustomId.
      Parameters:
      visitorCustomId - the visitor's custom id to set. A null value will remove this parameter

    • getVisitorFirstVisitTimestamp

      @Nullable public Long getVisitorFirstVisitTimestamp()
      Get the timestamp of the visitor's first visit.
      Returns:
      the timestamp of the visitor's first visit

    • setVisitorFirstVisitTimestamp

      public void setVisitorFirstVisitTimestamp(Long timestamp)
      Set the UNIX timestamp of this visitor's first visit. This could be set to the date where the user first started using your software/app, or when he/she created an account. This parameter is used to populate the Goals > Days to Conversion report.
      Parameters:
      timestamp - the timestamp of the visitor's first visit to set. A null value will remove this parameter

    • getVisitorId

      @Nullable public String getVisitorId()
      Get the visitor's id.
      Returns:
      the visitor's id

    • setVisitorId

      public void setVisitorId(String visitorId)
      Set the unique visitor ID, must be a 16 characters hexadecimal string. Every unique visitor must be assigned a different ID and this ID must not change after it is assigned. If this value is not set Matomo will still track visits, but the unique visitors metric might be less accurate.
      Parameters:
      visitorId - the visitor id to set. A null value will remove this parameter

    • getVisitorIp

      @Nullable public String getVisitorIp()
      Get the visitor's ip.
      Returns:
      the visitor's ip

    • setVisitorIp

      public void setVisitorIp(String visitorIp)
      Set the override value for the visitor IP (both IPv4 and IPv6 notations supported). AuthToken must first be set.
      Parameters:
      visitorIp - the visitor's ip to set. A null value will remove this parameter

    • getVisitorLatitude

      @Nullable public Double getVisitorLatitude()
      Get the visitor's latitude.
      Returns:
      the visitor's latitude

    • setVisitorLatitude

      public void setVisitorLatitude(Double latitude)
      Set an override value for the visitor's latitude, eg 22.456. AuthToken must first be set.
      Parameters:
      latitude - the visitor's latitude to set. A null value will remove this parameter

    • getVisitorLongitude

      @Nullable public Double getVisitorLongitude()
      Get the visitor's longitude.
      Returns:
      the visitor's longitude

    • setVisitorLongitude

      public void setVisitorLongitude(Double longitude)
      Set an override value for the visitor's longitude, eg 22.456. AuthToken must first be set.
      Parameters:
      longitude - the visitor's longitude to set. A null value will remove this parameter

    • getVisitorPreviousVisitTimestamp

      @Nullable public Long getVisitorPreviousVisitTimestamp()
      Get the timestamp of the visitor's previous visit.
      Returns:
      the timestamp of the visitor's previous visit

    • setVisitorPreviousVisitTimestamp

      public void setVisitorPreviousVisitTimestamp(Long timestamp)
      Set the UNIX timestamp of this visitor's previous visit. This parameter is used to populate the report Visitors > Engagement > Visits by days since last visit.
      Parameters:
      timestamp - the timestamp of the visitor's previous visit to set. A null value will remove this parameter

    • getVisitorRegion

      @Nullable public String getVisitorRegion()
      Get the visitor's region.
      Returns:
      the visitor's region

    • setVisitorRegion

      public void setVisitorRegion(String region)
      Set an override value for the region. Should be set to the two letter region code as defined by MaxMind's GeoIP databases. See here for a list of them for every country (the region codes are located in the second column, to the left of the region name and to the right of the country code).
      Parameters:
      region - the visitor's region to set. A null value will remove this parameter

    • getVisitorVisitCount

      @Nullable public Integer getVisitorVisitCount()
      Get the count of visits for this visitor.
      Returns:
      the count of visits for this visitor

    • setVisitorVisitCount

      public void setVisitorVisitCount(Integer visitorVisitCount)
      Set the current count of visits for this visitor. To set this value correctly, it would be required to store the value for each visitor in your application (using sessions or persisting in a database). Then you would manually increment the counts by one on each new visit or "session", depending on how you choose to define a visit. This value is used to populate the report Visitors > Engagement > Visits by visit number.
      Parameters:
      visitorVisitCount - the count of visits for this visitor to set. A null value will remove this parameter

    • getParameters

      public Map<String,Collection<Object>> getParameters()

    • getQueryString

      @Nonnull @Deprecated public String getQueryString()
      Deprecated.
      Use URIBuilder in conjunction with getParameters() and QueryParameters.fromMap(Map) ()} instead
      Get the query string represented by this object.
      Returns:
      the query string represented by this object

    • getUrlEncodedQueryString

      @Nonnull @Deprecated public String getUrlEncodedQueryString()
      Deprecated.
      Use URIBuilder in conjunction with getParameters() and QueryParameters.fromMap(Map) ()} instead
      Get the url encoded query string represented by this object.
      Returns:
      the url encoded query string represented by this object

    • getRandomHexString

      @Nonnull public static String getRandomHexString(int length)
      Get a random hexadecimal string of a specified length.
      Parameters:
      length - length of the string to produce
      Returns:
      a random string consisting only of hexadecimal characters

    • setParameter

      public void setParameter(@NonNull @NonNull String key, @Nullable Object value)
      Set a stored parameter.
      Parameters:
      key - the parameter's key
      value - the parameter's value. Removes the parameter if null

    • addParameter

      public void addParameter(@NonNull @NonNull String key, @NonNull @NonNull Object value)
      Add more values to the given parameter
      Parameters:
      key - the parameter's key. Must not be null
      value - the parameter's value. Must not be null