Package org.matomo.java.tracking

Class MatomoRequest.MatomoRequestBuilder

java.lang.Object
org.matomo.java.tracking.MatomoRequest.MatomoRequestBuilder
Direct Known Subclasses:
MatomoRequestBuilder
Enclosing class:
MatomoRequest
public static class MatomoRequest.MatomoRequestBuilder extends Object

  • Method Details

    • required

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

    • siteId

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

    • actionName

      public MatomoRequest.MatomoRequestBuilder actionName(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.
      Returns:
      this.

    • actionUrl

      public MatomoRequest.MatomoRequestBuilder actionUrl(String actionUrl)
      The full URL for the current action.
      Returns:
      this.

    • apiVersion

      public MatomoRequest.MatomoRequestBuilder apiVersion(String apiVersion)
      Defines the API version to use (default: 1).
      Returns:
      this.

    • visitorId

      public MatomoRequest.MatomoRequestBuilder visitorId(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.

      Returns:
      this.

    • newVisitor

      public MatomoRequest.MatomoRequestBuilder newVisitor(Boolean newVisitor)
      Tracks if the visitor is a returning visitor.

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

      Returns:
      this.

    • referrerUrl

      public MatomoRequest.MatomoRequestBuilder referrerUrl(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)
      Returns:
      this.

    • visitCustomVariables

      public MatomoRequest.MatomoRequestBuilder visitCustomVariables(CustomVariables visitCustomVariables)
      Custom variables are custom name-value pairs that you can assign to your visitors (or page views).
      Returns:
      this.

    • visitorVisitCount

      public MatomoRequest.MatomoRequestBuilder visitorVisitCount(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.
      Returns:
      this.

    • visitorPreviousVisitTimestamp

      public MatomoRequest.MatomoRequestBuilder visitorPreviousVisitTimestamp(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.
      Returns:
      this.

    • visitorFirstVisitTimestamp

      public MatomoRequest.MatomoRequestBuilder visitorFirstVisitTimestamp(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.
      Returns:
      this.

    • campaignName

      public MatomoRequest.MatomoRequestBuilder campaignName(String campaignName)
      The campaign name. This parameter will only be used for the first pageview of a visit.
      Returns:
      this.

    • campaignKeyword

      public MatomoRequest.MatomoRequestBuilder campaignKeyword(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.
      Returns:
      this.

    • deviceResolution

      public MatomoRequest.MatomoRequestBuilder deviceResolution(DeviceResolution deviceResolution)
      The resolution of the device the visitor is using.
      Returns:
      this.

    • currentHour

      public MatomoRequest.MatomoRequestBuilder currentHour(Integer currentHour)
      The current hour (local time).
      Returns:
      this.

    • currentMinute

      public MatomoRequest.MatomoRequestBuilder currentMinute(Integer currentMinute)
      The current minute (local time).
      Returns:
      this.

    • currentSecond

      public MatomoRequest.MatomoRequestBuilder currentSecond(Integer currentSecond)
      The current second (local time).
      Returns:
      this.

    • pluginFlash

      public MatomoRequest.MatomoRequestBuilder pluginFlash(Boolean pluginFlash)
      Does the visitor use the Adobe Flash Plugin.
      Returns:
      this.

    • pluginJava

      public MatomoRequest.MatomoRequestBuilder pluginJava(Boolean pluginJava)
      Does the visitor use the Java plugin.
      Returns:
      this.

    • pluginDirector

      public MatomoRequest.MatomoRequestBuilder pluginDirector(Boolean pluginDirector)
      Does the visitor use Director plugin.
      Returns:
      this.

    • pluginQuicktime

      public MatomoRequest.MatomoRequestBuilder pluginQuicktime(Boolean pluginQuicktime)
      Does the visitor use Quicktime plugin.
      Returns:
      this.

    • pluginRealPlayer

      public MatomoRequest.MatomoRequestBuilder pluginRealPlayer(Boolean pluginRealPlayer)
      Does the visitor use Realplayer plugin.
      Returns:
      this.

    • pluginPDF

      public MatomoRequest.MatomoRequestBuilder pluginPDF(Boolean pluginPDF)
      Does the visitor use a PDF plugin.
      Returns:
      this.

    • pluginWindowsMedia

      public MatomoRequest.MatomoRequestBuilder pluginWindowsMedia(Boolean pluginWindowsMedia)
      Does the visitor use a Windows Media plugin.
      Returns:
      this.

    • pluginGears

      public MatomoRequest.MatomoRequestBuilder pluginGears(Boolean pluginGears)
      Does the visitor use a Gears plugin.
      Returns:
      this.

    • pluginSilverlight

      public MatomoRequest.MatomoRequestBuilder pluginSilverlight(Boolean pluginSilverlight)
      Does the visitor use a Silverlight plugin.
      Returns:
      this.

    • supportsCookies

      public MatomoRequest.MatomoRequestBuilder supportsCookies(Boolean supportsCookies)
      Does the visitor's client is known to support cookies.
      Returns:
      this.

    • headerUserAgent

      public MatomoRequest.MatomoRequestBuilder headerUserAgent(String headerUserAgent)
      An override value for the User-Agent HTTP header field.
      Returns:
      this.

    • headerAcceptLanguage

      public MatomoRequest.MatomoRequestBuilder headerAcceptLanguage(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.
      Returns:
      this.

    • userId

      public MatomoRequest.MatomoRequestBuilder userId(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.
      Returns:
      this.

    • visitorCustomId

      public MatomoRequest.MatomoRequestBuilder visitorCustomId(VisitorId visitorCustomId)
      defines the visitor ID for this request.
      Returns:
      this.

    • newVisit

      public MatomoRequest.MatomoRequestBuilder newVisit(Boolean newVisit)
      will force a new visit to be created for this action.
      Returns:
      this.

    • pageCustomVariables

      public MatomoRequest.MatomoRequestBuilder pageCustomVariables(CustomVariables pageCustomVariables)
      Custom variables are custom name-value pairs that you can assign to your visitors (or page views).
      Returns:
      this.

    • outlinkUrl

      public MatomoRequest.MatomoRequestBuilder outlinkUrl(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.
      Returns:
      this.

    • downloadUrl

      public MatomoRequest.MatomoRequestBuilder downloadUrl(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.
      Returns:
      this.

    • searchQuery

      public MatomoRequest.MatomoRequestBuilder searchQuery(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
      Returns:
      this.

    • searchCategory

      public MatomoRequest.MatomoRequestBuilder searchCategory(String searchCategory)
      When search is specified, you can optionally specify a search category with this parameter.
      Returns:
      this.

    • searchResultsCount

      public MatomoRequest.MatomoRequestBuilder searchResultsCount(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.
      Returns:
      this.

    • pageViewId

      public MatomoRequest.MatomoRequestBuilder pageViewId(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.
      Returns:
      this.

    • goalId

      public MatomoRequest.MatomoRequestBuilder goalId(Integer goalId)
      If specified, the tracking request will trigger a conversion for the goal of the website being tracked with this ID. The value 0 tracks an ecommerce interaction.
      Returns:
      this.

    • ecommerceRevenue

      public MatomoRequest.MatomoRequestBuilder ecommerceRevenue(Double ecommerceRevenue)
      The grand total for the ecommerce order (required when tracking an ecommerce order).
      Returns:
      this.

    • characterSet

      public MatomoRequest.MatomoRequestBuilder characterSet(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
      Returns:
      this.

    • customAction

      public MatomoRequest.MatomoRequestBuilder customAction(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.
      Returns:
      this.

    • networkTime

      public MatomoRequest.MatomoRequestBuilder networkTime(Long networkTime)
      How long it took to connect to server.
      Returns:
      this.

    • serverTime

      public MatomoRequest.MatomoRequestBuilder serverTime(Long serverTime)
      How long it took the server to generate page.
      Returns:
      this.

    • transferTime

      public MatomoRequest.MatomoRequestBuilder transferTime(Long transferTime)
      How long it takes the browser to download the response from the server.
      Returns:
      this.

    • domProcessingTime

      public MatomoRequest.MatomoRequestBuilder domProcessingTime(Long domProcessingTime)
      How long the browser spends loading the webpage after the response was fully received until the user can start interacting with it.
      Returns:
      this.

    • domCompletionTime

      public MatomoRequest.MatomoRequestBuilder domCompletionTime(Long domCompletionTime)
      How long it takes for the browser to load media and execute any Javascript code listening for the DOMContentLoaded event.
      Returns:
      this.

    • onloadTime

      public MatomoRequest.MatomoRequestBuilder onloadTime(Long onloadTime)
      How long it takes the browser to execute Javascript code waiting for the window.load event.
      Returns:
      this.

    • eventCategory

      public MatomoRequest.MatomoRequestBuilder eventCategory(String eventCategory)
      eg. Videos, Music, Games...
      Returns:
      this.

    • eventAction

      public MatomoRequest.MatomoRequestBuilder eventAction(String eventAction)
      An event action like Play, Pause, Duration, Add Playlist, Downloaded, Clicked...
      Returns:
      this.

    • eventName

      public MatomoRequest.MatomoRequestBuilder eventName(String eventName)
      The event name for example a Movie name, or Song name, or File name...
      Returns:
      this.

    • eventValue

      public MatomoRequest.MatomoRequestBuilder eventValue(Double eventValue)
      Some numeric value that represents the event value.
      Returns:
      this.

    • contentName

      public MatomoRequest.MatomoRequestBuilder contentName(String contentName)
      The name of the content. For instance 'Ad Foo Bar'
      Returns:
      this.

    • contentPiece

      public MatomoRequest.MatomoRequestBuilder contentPiece(String contentPiece)
      The actual content piece. For instance the path to an image, video, audio, any text
      Returns:
      this.

    • contentTarget

      public MatomoRequest.MatomoRequestBuilder contentTarget(String contentTarget)
      The target of the content. For instance the URL of a landing page
      Returns:
      this.

    • contentInteraction

      public MatomoRequest.MatomoRequestBuilder contentInteraction(String contentInteraction)
      The name of the interaction with the content. For instance a 'click'
      Returns:
      this.

    • ecommerceId

      public MatomoRequest.MatomoRequestBuilder ecommerceId(String ecommerceId)
      The unique string identifier for the ecommerce order (required when tracking an ecommerce order).
      Returns:
      this.

    • ecommerceItems

      public MatomoRequest.MatomoRequestBuilder ecommerceItems(EcommerceItems ecommerceItems)
      Items in the Ecommerce order.
      Returns:
      this.

    • ecommerceSubtotal

      public MatomoRequest.MatomoRequestBuilder ecommerceSubtotal(Double ecommerceSubtotal)
      The subtotal of the order; excludes shipping.
      Returns:
      this.

    • ecommerceTax

      public MatomoRequest.MatomoRequestBuilder ecommerceTax(Double ecommerceTax)
      Tax amount of the order.
      Returns:
      this.

    • ecommerceShippingCost

      public MatomoRequest.MatomoRequestBuilder ecommerceShippingCost(Double ecommerceShippingCost)
      Shipping cost of the order.
      Returns:
      this.

    • ecommerceDiscount

      public MatomoRequest.MatomoRequestBuilder ecommerceDiscount(Double ecommerceDiscount)
      Discount offered.
      Returns:
      this.

    • ecommerceLastOrderTimestamp

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

    • authToken

      public MatomoRequest.MatomoRequestBuilder authToken(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).
      Returns:
      this.

    • visitorIp

      public MatomoRequest.MatomoRequestBuilder visitorIp(String visitorIp)
      Override value for the visitor IP (both IPv4 and IPv6 notations supported).
      Returns:
      this.

    • requestTimestamp

      public MatomoRequest.MatomoRequestBuilder requestTimestamp(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.
      Returns:
      this.

    • visitorCountry

      public MatomoRequest.MatomoRequestBuilder visitorCountry(Country visitorCountry)
      An override value for the country. Must be a two-letter ISO 3166 Alpha-2 country code.
      Returns:
      this.

    • visitorRegion

      public MatomoRequest.MatomoRequestBuilder visitorRegion(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.
      Returns:
      this.

    • visitorCity

      public MatomoRequest.MatomoRequestBuilder visitorCity(String visitorCity)
      An override value for the city. The name of the city the visitor is located in, eg, Tokyo.
      Returns:
      this.

    • visitorLatitude

      public MatomoRequest.MatomoRequestBuilder visitorLatitude(Double visitorLatitude)
      An override value for the visitor's latitude, eg 22.456.
      Returns:
      this.

    • visitorLongitude

      public MatomoRequest.MatomoRequestBuilder visitorLongitude(Double visitorLongitude)
      An override value for the visitor's longitude, eg 22.456.
      Returns:
      this.

    • queuedTracking

      public MatomoRequest.MatomoRequestBuilder queuedTracking(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.
      Returns:
      this.

    • responseAsImage

      public MatomoRequest.MatomoRequestBuilder responseAsImage(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

      Returns:
      this.

    • ping

      public MatomoRequest.MatomoRequestBuilder ping(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.
      Returns:
      this.

    • trackBotRequests

      public MatomoRequest.MatomoRequestBuilder trackBotRequests(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.
      Returns:
      this.

    • randomValue

      public MatomoRequest.MatomoRequestBuilder randomValue(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.
      Returns:
      this.

    • debug

      public MatomoRequest.MatomoRequestBuilder debug(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.
      Returns:
      this.

    • crashMessage

      public MatomoRequest.MatomoRequestBuilder crashMessage(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

      Returns:
      this.

    • crashType

      public MatomoRequest.MatomoRequestBuilder crashType(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

      Returns:
      this.

    • crashCategory

      public MatomoRequest.MatomoRequestBuilder crashCategory(String crashCategory)
      Category of a crash to group crashes by.

      Custom action must be enabled for this.

      Optional for crash analytics

      Returns:
      this.

    • crashStackTrace

      public MatomoRequest.MatomoRequestBuilder crashStackTrace(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

      Returns:
      this.

    • crashLocation

      public MatomoRequest.MatomoRequestBuilder crashLocation(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

      Returns:
      this.

    • crashLine

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

      Custom action must be enabled for this.

      Optional for crash analytics

      Returns:
      this.

    • crashColumn

      public MatomoRequest.MatomoRequestBuilder crashColumn(Integer crashColumn)
      The column within the line where the crash occurred.

      Optional for crash analytics

      Returns:
      this.

    • sessionId

      public MatomoRequest.MatomoRequestBuilder sessionId(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.

      Returns:
      this.

    • dimensions

      public MatomoRequest.MatomoRequestBuilder dimensions(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

      Returns:
      this.

    • additionalParameters

      public MatomoRequest.MatomoRequestBuilder additionalParameters(Map<String,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.

      Returns:
      this.

    • headers

      public MatomoRequest.MatomoRequestBuilder headers(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.

      Returns:
      this.

    • cookies

      public MatomoRequest.MatomoRequestBuilder cookies(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.

      Returns:
      this.

    • build

      public MatomoRequest build()

    • toString

      public String toString()
      Overrides:
      toString in class Object