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

  • Constructor Details

  • Method Details

    • 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

      @Deprecated public void setCustomTrackingParameter(@NonNull @NonNull String key, @Nullable Object value)
      Deprecated.
      Use MatomoRequest.MatomoRequestBuilder.additionalParameters(Map) instead.
      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

      @Deprecated public void addCustomTrackingParameter(@NonNull @NonNull String key, @NonNull @NonNull Object value)
      Deprecated.
      Use MatomoRequest.MatomoRequestBuilder.additionalParameters(Map) instead.
      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

      @Deprecated public void clearCustomTrackingParameter()
      Deprecated.
      Please use MatomoRequest.MatomoRequestBuilder.additionalParameters(Map) instead so that you can manage the map yourself.
      Removes all custom tracking parameters.

    • enableEcommerce

      @Deprecated public void enableEcommerce()
      Deprecated.
      Please use setGoalId(Integer) instead
      Sets idgoal=0 in the request to track an ecommerce interaction: cart update or an ecommerce order.

    • getEcommerceItem

      @Nullable @Deprecated public EcommerceItem getEcommerceItem(int index)
      Deprecated.
      Use @link MatomoRequest.MatomoRequestBuilder.ecommerceItems(EcommerceItems) instead
      Get the EcommerceItem at the specified index.
      Parameters:
      index - the index of the EcommerceItem to return
      Returns:
      the EcommerceItem at the specified index

    • addEcommerceItem

      @Deprecated public void addEcommerceItem(@NonNull @NonNull EcommerceItem item)
      Deprecated.
      Use @link MatomoRequest.MatomoRequestBuilder.ecommerceItems(EcommerceItems) instead
      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

      @Deprecated public void clearEcommerceItems()
      Deprecated.
      Use @link MatomoRequest.MatomoRequestBuilder.ecommerceItems(EcommerceItems) instead
      Clears all EcommerceItem from this order.

    • getPageCustomVariable

      @Nullable @Deprecated public String getPageCustomVariable(String key)
      Deprecated.
      Use the getPageCustomVariables() 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

      @Deprecated @Nullable public CustomVariable getPageCustomVariable(int index)
      Deprecated.
      Use getPageCustomVariables() instead
      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(@NonNull @NonNull String key, @Nullable String value)
      Deprecated.
      Use getPageCustomVariables() 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

      @Deprecated public void setPageCustomVariable(@Nullable CustomVariable customVariable, int index)
      Deprecated.
      Use getPageCustomVariables() instead
      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

    • getRequestDatetime

      @Deprecated @Nullable public MatomoDate getRequestDatetime()
      Deprecated.
      Use getRequestTimestamp() instead
      Get the datetime of the request.
      Returns:
      the datetime of the request

    • setRequestDatetime

      @Deprecated public void setRequestDatetime(MatomoDate matomoDate)
      Deprecated.
      Use setRequestTimestamp(Instant) instead
      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:
      matomoDate - the datetime of the request to set. A null value will remove this parameter

    • getUserCustomVariable

      @Nullable @Deprecated public String getUserCustomVariable(String key)
      Deprecated.
      Use the getVisitCustomVariables() 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 @Deprecated public CustomVariable getVisitCustomVariable(int index)
      Deprecated.
      Use getVisitCustomVariables() instead
      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(@NonNull @NonNull String key, @Nullable String value)
      Deprecated.
      Use setVisitCustomVariables(CustomVariables) 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

      @Deprecated public void setVisitCustomVariable(@Nullable CustomVariable customVariable, int index)
      Deprecated.
      Use setVisitCustomVariables(CustomVariables) instead
      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.

    • setParameter

      @Deprecated public void setParameter(@NonNull @NonNull String parameterName, Object value)
      Deprecated.
      Use @link MatomoRequest.MatomoRequestBuilder.additionalParameters(Map) instead
      Sets a custom parameter to append to the Matomo tracking parameters.

      Attention: If a parameter with the same name already exists, it will be appended twice!

      Parameters:
      parameterName - The name of the query parameter to append. Must not be null or empty.
      value - The value of the query parameter to append. To remove the parameter, pass null.

    • builder

      @Deprecated public static MatomoRequestBuilder builder()
      Deprecated.
      Use request() instead.
      Creates a new MatomoRequest.MatomoRequestBuilder instance. Only here for backwards compatibility.

    • setDeviceResolution

      @Deprecated public void setDeviceResolution(@Nullable String deviceResolution)
      Deprecated.
      Use setDeviceResolution(DeviceResolution) instead.
      Parses the given device resolution string and sets the deviceResolution field.
      Parameters:
      deviceResolution - the device resolution string to parse. Format: "WIDTHxHEIGHT"

    • request

      public static MatomoRequest.MatomoRequestBuilder request()

    • getRequired

      public Boolean getRequired()
      The ID of the website we're tracking a visit/action for. Only needed, if no default site id is configured

    • getSiteId

      public Integer getSiteId()
      The ID of the website we're tracking a visit/action for. Only needed, if no default site id is configured

    • getActionName

      public String getActionName()
      The title of the action being tracked. For page tracks this is used as page title. If enabled in your installation you may use the category tree structure in this field. For example, "game / register new user" would then create a group "game" and add the item "register new user" in it.

    • getActionUrl

      public String getActionUrl()
      The full URL for the current action.

    • getApiVersion

      public String getApiVersion()
      Defines the API version to use (default: 1).

    • getVisitorId

      public VisitorId getVisitorId()
      The unique visitor ID. See VisitorId. Default is VisitorId.random()

      Since version 3.0.0 this parameter is of type VisitorId and not a String anymore. Use VisitorId.fromHex(String) to create a VisitorId from a hex string, VisitorId.fromUUID(UUID) to create it from a UUID or VisitorId.fromHash(long) to create it from a long value.

    • getNewVisitor

      public Boolean getNewVisitor()
      Tracks if the visitor is a returning visitor.

      This is done by storing a visitor ID in a 1st party cookie.

    • getReferrerUrl

      public String getReferrerUrl()
      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)

    • getVisitCustomVariables

      public CustomVariables getVisitCustomVariables()
      Custom variables are custom name-value pairs that you can assign to your visitors (or page views).

    • getVisitorVisitCount

      public Integer getVisitorVisitCount()
      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.

    • getVisitorPreviousVisitTimestamp

      public Instant getVisitorPreviousVisitTimestamp()
      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.

    • getVisitorFirstVisitTimestamp

      public Instant getVisitorFirstVisitTimestamp()
      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.

    • getCampaignName

      public String getCampaignName()
      The campaign name. This parameter will only be used for the first pageview of a visit.

    • getCampaignKeyword

      public String getCampaignKeyword()
      The campaign keyword (see Tracking Campaigns). Used to populate the Referrers > Campaigns report (clicking on a campaign loads all keywords for this campaign). This parameter will only be used for the first pageview of a visit.

    • getDeviceResolution

      public DeviceResolution getDeviceResolution()
      The resolution of the device the visitor is using.

    • getCurrentHour

      public Integer getCurrentHour()
      The current hour (local time).

    • getCurrentMinute

      public Integer getCurrentMinute()
      The current minute (local time).

    • getCurrentSecond

      public Integer getCurrentSecond()
      The current second (local time).

    • getPluginFlash

      public Boolean getPluginFlash()
      Does the visitor use the Adobe Flash Plugin.

    • getPluginJava

      public Boolean getPluginJava()
      Does the visitor use the Java plugin.

    • getPluginDirector

      public Boolean getPluginDirector()
      Does the visitor use Director plugin.

    • getPluginQuicktime

      public Boolean getPluginQuicktime()
      Does the visitor use Quicktime plugin.

    • getPluginRealPlayer

      public Boolean getPluginRealPlayer()
      Does the visitor use Realplayer plugin.

    • getPluginPDF

      public Boolean getPluginPDF()
      Does the visitor use a PDF plugin.

    • getPluginWindowsMedia

      public Boolean getPluginWindowsMedia()
      Does the visitor use a Windows Media plugin.

    • getPluginGears

      public Boolean getPluginGears()
      Does the visitor use a Gears plugin.

    • getPluginSilverlight

      public Boolean getPluginSilverlight()
      Does the visitor use a Silverlight plugin.

    • getSupportsCookies

      public Boolean getSupportsCookies()
      Does the visitor's client is known to support cookies.

    • getHeaderUserAgent

      public String getHeaderUserAgent()
      An override value for the User-Agent HTTP header field.

    • getHeaderAcceptLanguage

      public AcceptLanguage getHeaderAcceptLanguage()
      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.

    • getUserId

      public String getUserId()
      Defines 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). 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.

    • getVisitorCustomId

      public VisitorId getVisitorCustomId()
      defines the visitor ID for this request.

    • getNewVisit

      public Boolean getNewVisit()
      will force a new visit to be created for this action.

    • getPageCustomVariables

      public CustomVariables getPageCustomVariables()
      Custom variables are custom name-value pairs that you can assign to your visitors (or page views).

    • getOutlinkUrl

      public String getOutlinkUrl()
      An external URL the user has opened. Used for tracking outlink clicks. We recommend to also set the url parameter to this same value.

    • getDownloadUrl

      public String getDownloadUrl()
      URL of a file the user has downloaded. Used for tracking downloads. We recommend to also set the url parameter to this same value.

    • getSearchQuery

      public String getSearchQuery()
      The Site Search keyword. When specified, the request will not be tracked as a normal pageview but will instead be tracked as a Site Search request

    • getSearchCategory

      public String getSearchCategory()
      When search is specified, you can optionally specify a search category with this parameter.

    • getSearchResultsCount

      public Long getSearchResultsCount()
      When search is specified, we also recommend setting the search_count to the number of search results displayed on the results page. When keywords are tracked with &search_count=0 they will appear in the "No Result Search Keyword" report.

    • getPageViewId

      public UniqueId getPageViewId()
      Accepts a six character unique ID that identifies which actions were performed on a specific page view. When a page was viewed, all following tracking requests (such as events) during that page view should use the same pageview ID. Once another page was viewed a new unique ID should be generated. Use [0-9a-Z] as possible characters for the unique ID.

    • getGoalId

      public Integer getGoalId()
      If specified, the tracking request will trigger a conversion for the goal of the website being tracked with this ID.

    • getEcommerceRevenue

      public Double getEcommerceRevenue()
      The grand total for the ecommerce order (required when tracking an ecommerce order).

    • getCharacterSet

      public Charset getCharacterSet()
      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

    • getCustomAction

      public Boolean getCustomAction()
      can be optionally sent along any tracking request that isn't a page view. For example, it can be sent together with an event tracking request. The advantage being that should you ever disable the event plugin, then the event tracking requests will be ignored vs if the parameter is not set, a page view would be tracked even though it isn't a page view.

    • getNetworkTime

      public Long getNetworkTime()
      How long it took to connect to server.

    • getServerTime

      public Long getServerTime()
      How long it took the server to generate page.

    • getTransferTime

      public Long getTransferTime()
      How long it takes the browser to download the response from the server.

    • getDomProcessingTime

      public Long getDomProcessingTime()
      How long the browser spends loading the webpage after the response was fully received until the user can start interacting with it.

    • getDomCompletionTime

      public Long getDomCompletionTime()
      How long it takes for the browser to load media and execute any Javascript code listening for the DOMContentLoaded event.

    • getOnloadTime

      public Long getOnloadTime()
      How long it takes the browser to execute Javascript code waiting for the window.load event.

    • getEventCategory

      public String getEventCategory()
      eg. Videos, Music, Games...

    • getEventAction

      public String getEventAction()
      An event action like Play, Pause, Duration, Add Playlist, Downloaded, Clicked...

    • getEventName

      public String getEventName()
      The event name for example a Movie name, or Song name, or File name...

    • getEventValue

      public Double getEventValue()
      Some numeric value that represents the event value.

    • getContentName

      public String getContentName()
      The name of the content. For instance 'Ad Foo Bar'

    • getContentPiece

      public String getContentPiece()
      The actual content piece. For instance the path to an image, video, audio, any text

    • getContentTarget

      public String getContentTarget()
      The target of the content. For instance the URL of a landing page

    • getContentInteraction

      public String getContentInteraction()
      The name of the interaction with the content. For instance a 'click'

    • getEcommerceId

      public String getEcommerceId()
      he unique string identifier for the ecommerce order (required when tracking an ecommerce order). you must set &idgoal=0 in the request to track an ecommerce interaction: cart update or an ecommerce order.

    • getEcommerceItems

      public EcommerceItems getEcommerceItems()
      Items in the Ecommerce order.

    • getEcommerceSubtotal

      public Double getEcommerceSubtotal()
      The subtotal of the order; excludes shipping.

    • getEcommerceTax

      public Double getEcommerceTax()
      Tax amount of the order.

    • getEcommerceShippingCost

      public Double getEcommerceShippingCost()
      Shipping cost of the order.

    • getEcommerceDiscount

      public Double getEcommerceDiscount()
      Discount offered.

    • getEcommerceLastOrderTimestamp

      public Instant getEcommerceLastOrderTimestamp()
      The UNIX timestamp of this customer's last ecommerce order. This value is used to process the "Days since last order" report.

    • getAuthToken

      public String getAuthToken()
      32 character authorization key used to authenticate the API request. We recommend to create a user specifically for accessing the Tracking API, and give the user only write permission on the website(s).

    • getVisitorIp

      public String getVisitorIp()
      Override value for the visitor IP (both IPv4 and IPv6 notations supported).

    • getRequestTimestamp

      public Instant getRequestTimestamp()
      Override for the datetime of the request (normally the current time is used). This can be used to record visits and page views in the past.

    • getVisitorCountry

      public Country getVisitorCountry()
      An override value for the country. Must be a two-letter ISO 3166 Alpha-2 country code.

    • getVisitorRegion

      public String getVisitorRegion()
      An override value for the region. Should be set to a ISO 3166-2 region code, which are used by MaxMind's and DB-IP's GeoIP2 databases. See here for a list of them for every country.

    • getVisitorCity

      public String getVisitorCity()
      An override value for the city. The name of the city the visitor is located in, eg, Tokyo.

    • getVisitorLatitude

      public Double getVisitorLatitude()
      An override value for the visitor's latitude, eg 22.456.

    • getVisitorLongitude

      public Double getVisitorLongitude()
      An override value for the visitor's longitude, eg 22.456.

    • getQueuedTracking

      public Boolean getQueuedTracking()
      When set to false, the queued tracking handler won't be used and instead the tracking request will be executed directly. This can be useful when you need to debug a tracking problem or want to test that the tracking works in general.

    • getResponseAsImage

      public Boolean getResponseAsImage()
      If set to 0 (send_image=0) Matomo will respond with an 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 (like Chrome Apps). Available since Matomo 2.10.0

      Default is false

    • getPing

      public Boolean getPing()
      If set to true, the request will be a Heartbeat request which will not track any new activity (such as a new visit, new action or new goal). The heartbeat request will only update the visit's total time to provide accurate "Visit duration" metric when this parameter is set. It won't record any other data. This means by sending an additional tracking request when the user leaves your site or app with &ping=1, you fix the issue where the time spent of the last page visited is reported as 0 seconds.

    • getTrackBotRequests

      public Boolean getTrackBotRequests()
      By default, Matomo does not track bots. If you use the Tracking HTTP API directly, you may be interested in tracking bot requests.

    • getRandomValue

      public RandomValue getRandomValue()
      Meant to hold a random value that is generated before each request. Using it helps avoid the tracking request being cached by the browser or a proxy.

    • getDebug

      public Boolean getDebug()
      Meant to hold a random value that is generated before each request. Using it helps avoid the tracking request being cached by the browser or a proxy.

    • getCrashMessage

      public String getCrashMessage()
      Contains an error message describing the error that occurred during the last tracking request.

      Custom action must be enabled for this.

      Required for crash analytics

    • getCrashType

      public String getCrashType()
      The type of exception that occurred during the last tracking request.

      Custom action must be enabled for this.

      Typically a fully qualified class name of the exception, e.g. java.lang.NullPointerException.

      Optional for crash analytics

    • getCrashCategory

      public String getCrashCategory()
      Category of a crash to group crashes by.

      Custom action must be enabled for this.

      Optional for crash analytics

    • getCrashStackTrace

      public String getCrashStackTrace()
      A stack trace of the exception that occurred during the last tracking request.

      Custom action must be enabled for this.

      Optional for crash analytics

    • getCrashLocation

      public String getCrashLocation()
      The originating source of the crash.

      Could be a source file URI or something similar

      Custom action must be enabled for this.

      Optional for crash analytics

    • getCrashLine

      public Integer getCrashLine()
      The line number of the crash source, where the crash occurred.

      Custom action must be enabled for this.

      Optional for crash analytics

    • getCrashColumn

      public Integer getCrashColumn()
      The column within the line where the crash occurred.

      Optional for crash analytics

    • getSessionId

      public String getSessionId()
      The Matomo session ID sent as a cookie MATOMO_SESSID.

      If not null a cookie with the name MATOMO_SESSID will be sent with the value of this parameter.

    • getDimensions

      public Map<Long,Object> getDimensions()
      Custom Dimension values for specific Custom Dimension IDs.

      Custom Dimensions plugin must be installed. See the Custom Dimensions guide. Requires Matomo at least 2.15.1

    • getAdditionalParameters

      public Map<String,Collection<Object>> getAdditionalParameters()
      Allows you to specify additional HTTP request parameters that will be sent to Matomo.

      For example, you can use this to set the Accept-Language header, or to set the Content-Type.

    • getHeaders

      public Map<String,String> getHeaders()
      You can set additional HTTP headers for the request sent to Matomo.

      For example, you can use this to set the Accept-Language header, or to set the Content-Type.

    • getCookies

      public Map<String,String> getCookies()
      Appends additional cookies to the request.

      This allows you to add Matomo specific cookies, like _pk_id or _pk_sess coming from Matomo responses to the request.

    • setRequired

      public void setRequired(Boolean required)
      The ID of the website we're tracking a visit/action for. Only needed, if no default site id is configured

    • setSiteId

      public void setSiteId(Integer siteId)
      The ID of the website we're tracking a visit/action for. Only needed, if no default site id is configured

    • setActionName

      public void setActionName(String actionName)
      The title of the action being tracked. For page tracks this is used as page title. If enabled in your installation you may use the category tree structure in this field. For example, "game / register new user" would then create a group "game" and add the item "register new user" in it.

    • setActionUrl

      public void setActionUrl(String actionUrl)
      The full URL for the current action.

    • setApiVersion

      public void setApiVersion(String apiVersion)
      Defines the API version to use (default: 1).

    • setVisitorId

      public void setVisitorId(VisitorId visitorId)
      The unique visitor ID. See VisitorId. Default is VisitorId.random()

      Since version 3.0.0 this parameter is of type VisitorId and not a String anymore. Use VisitorId.fromHex(String) to create a VisitorId from a hex string, VisitorId.fromUUID(UUID) to create it from a UUID or VisitorId.fromHash(long) to create it from a long value.

    • setNewVisitor

      public void setNewVisitor(Boolean newVisitor)
      Tracks if the visitor is a returning visitor.

      This is done by storing a visitor ID in a 1st party cookie.

    • setReferrerUrl

      public void setReferrerUrl(String referrerUrl)
      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)

    • setVisitCustomVariables

      public void setVisitCustomVariables(CustomVariables visitCustomVariables)
      Custom variables are custom name-value pairs that you can assign to your visitors (or page views).

    • setVisitorVisitCount

      public void setVisitorVisitCount(Integer visitorVisitCount)
      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.

    • setVisitorPreviousVisitTimestamp

      public void setVisitorPreviousVisitTimestamp(Instant visitorPreviousVisitTimestamp)
      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.

    • setVisitorFirstVisitTimestamp

      public void setVisitorFirstVisitTimestamp(Instant visitorFirstVisitTimestamp)
      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.

    • setCampaignName

      public void setCampaignName(String campaignName)
      The campaign name. This parameter will only be used for the first pageview of a visit.

    • setCampaignKeyword

      public void setCampaignKeyword(String campaignKeyword)
      The campaign keyword (see Tracking Campaigns). Used to populate the Referrers > Campaigns report (clicking on a campaign loads all keywords for this campaign). This parameter will only be used for the first pageview of a visit.

    • setDeviceResolution

      public void setDeviceResolution(DeviceResolution deviceResolution)
      The resolution of the device the visitor is using.

    • setCurrentHour

      public void setCurrentHour(Integer currentHour)
      The current hour (local time).

    • setCurrentMinute

      public void setCurrentMinute(Integer currentMinute)
      The current minute (local time).

    • setCurrentSecond

      public void setCurrentSecond(Integer currentSecond)
      The current second (local time).

    • setPluginFlash

      public void setPluginFlash(Boolean pluginFlash)
      Does the visitor use the Adobe Flash Plugin.

    • setPluginJava

      public void setPluginJava(Boolean pluginJava)
      Does the visitor use the Java plugin.

    • setPluginDirector

      public void setPluginDirector(Boolean pluginDirector)
      Does the visitor use Director plugin.

    • setPluginQuicktime

      public void setPluginQuicktime(Boolean pluginQuicktime)
      Does the visitor use Quicktime plugin.

    • setPluginRealPlayer

      public void setPluginRealPlayer(Boolean pluginRealPlayer)
      Does the visitor use Realplayer plugin.

    • setPluginPDF

      public void setPluginPDF(Boolean pluginPDF)
      Does the visitor use a PDF plugin.

    • setPluginWindowsMedia

      public void setPluginWindowsMedia(Boolean pluginWindowsMedia)
      Does the visitor use a Windows Media plugin.

    • setPluginGears

      public void setPluginGears(Boolean pluginGears)
      Does the visitor use a Gears plugin.

    • setPluginSilverlight

      public void setPluginSilverlight(Boolean pluginSilverlight)
      Does the visitor use a Silverlight plugin.

    • setSupportsCookies

      public void setSupportsCookies(Boolean supportsCookies)
      Does the visitor's client is known to support cookies.

    • setHeaderUserAgent

      public void setHeaderUserAgent(String headerUserAgent)
      An override value for the User-Agent HTTP header field.

    • setHeaderAcceptLanguage

      public void setHeaderAcceptLanguage(AcceptLanguage headerAcceptLanguage)
      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.

    • setUserId

      public void setUserId(String userId)
      Defines 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). 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.

    • setVisitorCustomId

      public void setVisitorCustomId(VisitorId visitorCustomId)
      defines the visitor ID for this request.

    • setNewVisit

      public void setNewVisit(Boolean newVisit)
      will force a new visit to be created for this action.

    • setPageCustomVariables

      public void setPageCustomVariables(CustomVariables pageCustomVariables)
      Custom variables are custom name-value pairs that you can assign to your visitors (or page views).

    • setOutlinkUrl

      public void setOutlinkUrl(String outlinkUrl)
      An external URL the user has opened. Used for tracking outlink clicks. We recommend to also set the url parameter to this same value.

    • setDownloadUrl

      public void setDownloadUrl(String downloadUrl)
      URL of a file the user has downloaded. Used for tracking downloads. We recommend to also set the url parameter to this same value.

    • setSearchQuery

      public void setSearchQuery(String searchQuery)
      The Site Search keyword. When specified, the request will not be tracked as a normal pageview but will instead be tracked as a Site Search request

    • setSearchCategory

      public void setSearchCategory(String searchCategory)
      When search is specified, you can optionally specify a search category with this parameter.

    • setSearchResultsCount

      public void setSearchResultsCount(Long searchResultsCount)
      When search is specified, we also recommend setting the search_count to the number of search results displayed on the results page. When keywords are tracked with &search_count=0 they will appear in the "No Result Search Keyword" report.

    • setPageViewId

      public void setPageViewId(UniqueId pageViewId)
      Accepts a six character unique ID that identifies which actions were performed on a specific page view. When a page was viewed, all following tracking requests (such as events) during that page view should use the same pageview ID. Once another page was viewed a new unique ID should be generated. Use [0-9a-Z] as possible characters for the unique ID.

    • setGoalId

      public void setGoalId(Integer goalId)
      If specified, the tracking request will trigger a conversion for the goal of the website being tracked with this ID.

    • setEcommerceRevenue

      public void setEcommerceRevenue(Double ecommerceRevenue)
      The grand total for the ecommerce order (required when tracking an ecommerce order).

    • 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

    • setCustomAction

      public void setCustomAction(Boolean customAction)
      can be optionally sent along any tracking request that isn't a page view. For example, it can be sent together with an event tracking request. The advantage being that should you ever disable the event plugin, then the event tracking requests will be ignored vs if the parameter is not set, a page view would be tracked even though it isn't a page view.

    • setNetworkTime

      public void setNetworkTime(Long networkTime)
      How long it took to connect to server.

    • setServerTime

      public void setServerTime(Long serverTime)
      How long it took the server to generate page.

    • setTransferTime

      public void setTransferTime(Long transferTime)
      How long it takes the browser to download the response from the server.

    • setDomProcessingTime

      public void setDomProcessingTime(Long domProcessingTime)
      How long the browser spends loading the webpage after the response was fully received until the user can start interacting with it.

    • setDomCompletionTime

      public void setDomCompletionTime(Long domCompletionTime)
      How long it takes for the browser to load media and execute any Javascript code listening for the DOMContentLoaded event.

    • setOnloadTime

      public void setOnloadTime(Long onloadTime)
      How long it takes the browser to execute Javascript code waiting for the window.load event.

    • setEventCategory

      public void setEventCategory(String eventCategory)
      eg. Videos, Music, Games...

    • setEventAction

      public void setEventAction(String eventAction)
      An event action like Play, Pause, Duration, Add Playlist, Downloaded, Clicked...

    • setEventName

      public void setEventName(String eventName)
      The event name for example a Movie name, or Song name, or File name...

    • setEventValue

      public void setEventValue(Double eventValue)
      Some numeric value that represents the event value.

    • setContentName

      public void setContentName(String contentName)
      The name of the content. For instance 'Ad Foo Bar'

    • setContentPiece

      public void setContentPiece(String contentPiece)
      The actual content piece. For instance the path to an image, video, audio, any text

    • setContentTarget

      public void setContentTarget(String contentTarget)
      The target of the content. For instance the URL of a landing page

    • setContentInteraction

      public void setContentInteraction(String contentInteraction)
      The name of the interaction with the content. For instance a 'click'

    • setEcommerceId

      public void setEcommerceId(String ecommerceId)
      he unique string identifier for the ecommerce order (required when tracking an ecommerce order). you must set &idgoal=0 in the request to track an ecommerce interaction: cart update or an ecommerce order.

    • setEcommerceItems

      public void setEcommerceItems(EcommerceItems ecommerceItems)
      Items in the Ecommerce order.

    • setEcommerceSubtotal

      public void setEcommerceSubtotal(Double ecommerceSubtotal)
      The subtotal of the order; excludes shipping.

    • setEcommerceTax

      public void setEcommerceTax(Double ecommerceTax)
      Tax amount of the order.

    • setEcommerceShippingCost

      public void setEcommerceShippingCost(Double ecommerceShippingCost)
      Shipping cost of the order.

    • setEcommerceDiscount

      public void setEcommerceDiscount(Double ecommerceDiscount)
      Discount offered.

    • setEcommerceLastOrderTimestamp

      public void setEcommerceLastOrderTimestamp(Instant ecommerceLastOrderTimestamp)
      The UNIX timestamp of this customer's last ecommerce order. This value is used to process the "Days since last order" report.

    • setAuthToken

      public void setAuthToken(String authToken)
      32 character authorization key used to authenticate the API request. We recommend to create a user specifically for accessing the Tracking API, and give the user only write permission on the website(s).

    • setVisitorIp

      public void setVisitorIp(String visitorIp)
      Override value for the visitor IP (both IPv4 and IPv6 notations supported).

    • setRequestTimestamp

      public void setRequestTimestamp(Instant requestTimestamp)
      Override for the datetime of the request (normally the current time is used). This can be used to record visits and page views in the past.

    • setVisitorCountry

      public void setVisitorCountry(Country visitorCountry)
      An override value for the country. Must be a two-letter ISO 3166 Alpha-2 country code.

    • setVisitorRegion

      public void setVisitorRegion(String visitorRegion)
      An override value for the region. Should be set to a ISO 3166-2 region code, which are used by MaxMind's and DB-IP's GeoIP2 databases. See here for a list of them for every country.

    • setVisitorCity

      public void setVisitorCity(String visitorCity)
      An override value for the city. The name of the city the visitor is located in, eg, Tokyo.

    • setVisitorLatitude

      public void setVisitorLatitude(Double visitorLatitude)
      An override value for the visitor's latitude, eg 22.456.

    • setVisitorLongitude

      public void setVisitorLongitude(Double visitorLongitude)
      An override value for the visitor's longitude, eg 22.456.

    • setQueuedTracking

      public void setQueuedTracking(Boolean queuedTracking)
      When set to false, the queued tracking handler won't be used and instead the tracking request will be executed directly. This can be useful when you need to debug a tracking problem or want to test that the tracking works in general.

    • setResponseAsImage

      public void setResponseAsImage(Boolean responseAsImage)
      If set to 0 (send_image=0) Matomo will respond with an 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 (like Chrome Apps). Available since Matomo 2.10.0

      Default is false

    • setPing

      public void setPing(Boolean ping)
      If set to true, the request will be a Heartbeat request which will not track any new activity (such as a new visit, new action or new goal). The heartbeat request will only update the visit's total time to provide accurate "Visit duration" metric when this parameter is set. It won't record any other data. This means by sending an additional tracking request when the user leaves your site or app with &ping=1, you fix the issue where the time spent of the last page visited is reported as 0 seconds.

    • setTrackBotRequests

      public void setTrackBotRequests(Boolean trackBotRequests)
      By default, Matomo does not track bots. If you use the Tracking HTTP API directly, you may be interested in tracking bot requests.

    • setRandomValue

      public void setRandomValue(RandomValue randomValue)
      Meant to hold a random value that is generated before each request. Using it helps avoid the tracking request being cached by the browser or a proxy.

    • setDebug

      public void setDebug(Boolean debug)
      Meant to hold a random value that is generated before each request. Using it helps avoid the tracking request being cached by the browser or a proxy.

    • setCrashMessage

      public void setCrashMessage(String crashMessage)
      Contains an error message describing the error that occurred during the last tracking request.

      Custom action must be enabled for this.

      Required for crash analytics

    • setCrashType

      public void setCrashType(String crashType)
      The type of exception that occurred during the last tracking request.

      Custom action must be enabled for this.

      Typically a fully qualified class name of the exception, e.g. java.lang.NullPointerException.

      Optional for crash analytics

    • setCrashCategory

      public void setCrashCategory(String crashCategory)
      Category of a crash to group crashes by.

      Custom action must be enabled for this.

      Optional for crash analytics

    • setCrashStackTrace

      public void setCrashStackTrace(String crashStackTrace)
      A stack trace of the exception that occurred during the last tracking request.

      Custom action must be enabled for this.

      Optional for crash analytics

    • setCrashLocation

      public void setCrashLocation(String crashLocation)
      The originating source of the crash.

      Could be a source file URI or something similar

      Custom action must be enabled for this.

      Optional for crash analytics

    • setCrashLine

      public void setCrashLine(Integer crashLine)
      The line number of the crash source, where the crash occurred.

      Custom action must be enabled for this.

      Optional for crash analytics

    • setCrashColumn

      public void setCrashColumn(Integer crashColumn)
      The column within the line where the crash occurred.

      Optional for crash analytics

    • setSessionId

      public void setSessionId(String sessionId)
      The Matomo session ID sent as a cookie MATOMO_SESSID.

      If not null a cookie with the name MATOMO_SESSID will be sent with the value of this parameter.

    • setDimensions

      public void setDimensions(Map<Long,Object> dimensions)
      Custom Dimension values for specific Custom Dimension IDs.

      Custom Dimensions plugin must be installed. See the Custom Dimensions guide. Requires Matomo at least 2.15.1

    • setAdditionalParameters

      public void setAdditionalParameters(Map<String,Collection<Object>> additionalParameters)
      Allows you to specify additional HTTP request parameters that will be sent to Matomo.

      For example, you can use this to set the Accept-Language header, or to set the Content-Type.

    • setHeaders

      public void setHeaders(Map<String,String> headers)
      You can set additional HTTP headers for the request sent to Matomo.

      For example, you can use this to set the Accept-Language header, or to set the Content-Type.

    • setCookies

      public void setCookies(Map<String,String> cookies)
      Appends additional cookies to the request.

      This allows you to add Matomo specific cookies, like _pk_id or _pk_sess coming from Matomo responses to the request.

    • toString

      public String toString()
      Overrides:
      toString in class Object