matomo

package module
v0.0.0-...-1080e55 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 29, 2022 License: MIT Imports: 9 Imported by: 0

README

Go-Matomo

A simple Go SDK for sending data to a Matomo instance. This is useful for tracking user events on the server-side and publishing them to a Matomo site.

Installation

go get github.com/hentaiOS-Infrastructure/go-matomo

Configuration

First, you must have a working Matomo installation. Not sure how to get started with Matomo? Refer to their website.

Sending analytics and events up is pretty straight-forward. Most data does not require any authentication, so the only configuration the SDK requires at this time is the domain of the installation. This is passed in through the environment to your running Go code:

MATOMO_DOMAIN=https://matomo.mydomain.com

Note the full protocol and domain. If Matomo is behind a different port, include that as well. Also note the lack of /matomo.php at the end. The SDK will take care of that for you.

When included, the SDK will run its init function to set up the configuration and read the domain. If one is not provided, you will see an error in the terminal. We will not panic or cause your application to stop due to this configuration error, so it is your responsibility to monitor for it.

If you are running the SDK on a system that is only responsible for reporting to a single site, then you can also specify the Site ID. This will allow the SDK to fill that in for you and also allows using the environment for different situations (such as testing the same Docker image from local to development to production):

MATOMO_SITE_ID=1

Usage

Upon startup, the SDK will call it's init func, which calls its Setup func. This prepares the SDK for usage. When you have an event to send up, you will populate a matomo.Parameters{} struct. Most fields are optional. If they are nil, they will not be included. Since pointers are used to denote presence (as default values in Go are interpreted as present values by Matomo), you will want to use the *Ptr helper functions. For example:

params := matomo.Parameters{
  RecommendedParameters: &matomo.RecommendedParameters{
    ActionName: matomo.StringPtr("visit"),
    URL: matomo.StringPtr("/users/me"),
    VisitorID: matomo.StringPtr("UNIQUE_HEX_VALUE"),
  },
  UserParameters: &matomo.UserParameters{
    UserID: matomo.StringPtr("mytestuser@mysite.com"),
  },
  EventTrackingParameters: &matomo.EventTrackingParameters{
    Category: matomo.StringPtr("site visit"),
    Action: matomo.StringPtr("loaded"),
    Name: matomo.StringPtr("user profile load"),
    Value: matomo.Float64Ptr(1.0),
  },
}
err := matomo.Send(&params)

The RecommendedParameters.VisitorID field may trip you up. If you have the user's DB identifier or some other identifying material, you can convert it to a 16 character hex. Or you can generate a pseudorandom one with the IP of the user, or whatever other identifying information you are comfortable collecting.

Contributing

Contributors are welcome. You should raise an issue or communicate with us prior to committing any significant effort to ensure that your desired changes are compatible with where we want this library to go. Read more in the CONTRIBUTING.md document.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BoolPtr 

func BoolPtr(input bool) *bool

BoolPtr converts a static bool to a pointer for use in the api

func Float64Ptr 

func Float64Ptr(input float64) *float64

Float64Ptr converts a static float to a pointer for use in the api

func Int64Ptr 

func Int64Ptr(input int64) *int64

Int64Ptr converts a static int64 to a pointer for use in the api

func Send 

func Send(params *Parameters) error

Send is a helper function that reads the siteID from the configuration file rather than requiring the user to provide it.

func SendToSite 

func SendToSite(siteID string, params *Parameters) error

SendToSite sends the parameters to Matomo instance. Matomo wants all of the data in the query string, regardless of whether GET or POST is used.

func Setup 

func Setup()

func StringPtr 

func StringPtr(input string) *string

StringPtr converts a static string to a pointer for use in the api

Types

type ActionParameters 

type ActionParameters struct {
	// 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.
	ActionName *string `json:"action_name" matomo:"action_name"`
	// The full URL for the current action.
	Url *string `json:"url" matomo:"url"`
	// 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 (formerly Piwik) will still track visits, but the unique visitors metric might be less accurate.
	VisitorID *string `json:"_id" matomo:"_id"`
	// URL of a file the user has downloaded. Used for tracking downloads.
	Download *string `json:"download" matomo:"download"`
	// An external URL the user has opened. Used for tracking outlink clicks.
	Link *string `json:"link" matomo:"link"`
}

type Configuration 

type Configuration struct {
	Domain    string
	AuthToken string
	SiteID    string // if not provided, will be required in the call
	Rec       string // currently must always be set to 1
}

type ContentTrackingParameters 

type ContentTrackingParameters struct {
	// The name of the content. For instance 'Ad Foo Bar'
	Name *string `json:"c_n" matomo:"c_n"`
	// The actual content piece. For instance the path to an image, video, audio, any text
	Piece *string `json:"c_p" matomo:"c_p"`
	// The target of the content. For instance the URL of a landing page
	Target *string `json:"c_t" matomo:"c_t"`
	// The name of the interaction with the content. For instance a 'click'
	Interaction *string `json:"c_i" matomo:"c_i"`
}

type EcommerceParameters 

type EcommerceParameters struct {
}

type EventTrackingParameters 

type EventTrackingParameters struct {
	// The event category. Must not be empty. (eg. Videos, Music, Games...)
	Category *string `json:"e_c" matomo:"e_c"`
	// The event action. Must not be empty. (eg. Play, Pause, Duration, Add Playlist, Downloaded, Clicked...)
	Action *string `json:"e_a" matomo:"e_a"`
	// The event name. (eg. a Movie name, or Song name, or File name...)
	Name *string `json:"e_n" matomo:"e_n"`
	// The event value. Must be a float or integer value (numeric), not a string.
	Value *float64 `json:"e_v" matomo:"e_v"`
}

EventTrackParameters add context to a user's actions on your platform.

type OtherParameters 

type OtherParameters struct {
	// Override value for the visitor IP (both IPv4 and IPv6 notations supported).
	CIP *string `json:"cip" matomo:"cip"`
}

type PagePerformanceParameters 

type PagePerformanceParameters struct {
}

type Parameters 

type Parameters struct {
	RecommendedParameters     *RecommendedParameters
	UserParameters            *UserParameters
	ActionParameters          *ActionParameters
	PagePerformanceParameters *PagePerformanceParameters
	EventTrackingParameters   *EventTrackingParameters
	ContentTrackingParameters *ContentTrackingParameters
	EcommerceParameters       *EcommerceParameters
	OtherParameters           *OtherParameters
}

Parameters are the content that gets sent to the API. If the field is nil, it is skipped. If it isn't nil, it will be automatically encoded and added to the body of the request. sendImage will be set to false. We have a matomo tag, but aren't currently using it and just using hard coded values. Keep in mind that many of these fields are included for completeness sake and will not likely be known or relevant in a server-side context (eg: the user's resolution).

type RecommendedParameters 

type RecommendedParameters struct {
	// 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. If not set, the SDK will set it for you.
	Rand *int64 `json:"rand" matomo:"rand"` // generated at call time if not provided
	// The parameter &apiv=1 defines the api version to use (currently always set to 1). The SDK sets this for you.
	APIV *int64 `json:"apiv" matomo:"apiv"` // always set to 1
	// Matomo will respond with a HTTP 204 response code instead of a GIF image.
	SendImage *int64 `json:"send_image" matomo:"send_image"`
}

RecommendedParameters are the recommended parameters that really should be provided on each call if available

type UserParameters 

type UserParameters struct {
	// 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).
	URLRef *string `json:"urlref" matomo:"urlref"`
	//  Visit scope custom variables. This is a JSON encoded string of the custom variable array.
	CVar *string `json:"_cvar" matomo:"_cvar"`
	// 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.
	IDVC *int64 `json:"_idvc" matomo:"_idvc"`
	// 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.
	ViewTS *int64 `json:"_viewts" matomo:"_viewts"`
	// 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.
	IDTS *int64 `json:"_idts" matomo:"_idts"`
	// The Campaign name. Used to populate the Referrers > Campaigns report. Note: this parameter will only be used for the first pageview of a visit.
	CampaignName *string `json:"_rcn" matomo:"_rcn"`
	// The Campaign Keyword. 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.
	CampaignKeyword *string `json:"_rck" matomo:"_rck"`
	//  The resolution of the device the visitor is using, eg 1280x1024.
	Resolution *string `json:"res" matomo:"res"`
	// The current hour (local time). The SDK will automatically set this if you don't.
	CurrentHour *string `json:"h" matomo:"h"`
	// The current minute (local time). The SDK will automatically set this if you don't.
	CurrentMinute *string `json:"m" matomo:"m"`
	// The current second (local time). The SDK will automatically set this if you don't.
	CurrentSecond *string `json:"s" matomo:"s"`
	// Various user plugins that the server likely won't know about.
	UserPlugins *UserPlugins `json:"plugins" matomo:"-"`
	// When set to 1, the visitor's client is known to support cookies.
	CookiesSupported *bool `json:"cookie" matomo:"cookie"`
	// An override value for the User-Agent HTTP header field. The user agent is used to detect the operating system and browser used.
	UserAgent *string `json:"ua" matomo:"ua"`
	// 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.
	Lang *string `json:"lang" matomo:"lang"`
	// Defines the User ID for this request. User ID is any non-empty unique string identifying the user (such as an email address or an 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 visits log, the Visitor profile, and you can Segment reports for one or several User ID (userId segment). 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.
	UserID *string `json:"uid" matomo:"uid"`
	// If set to 1, will force a new visit to be created for this action. T
	NewVisit *bool `json:"new_visit" matomo:"new_visit"`
}

UserParameters are user specific parameters for the event

type UserPlugins 

type UserPlugins struct {
	Flash       *bool `json:"fla" matomo:"fla"`
	Java        *bool `json:"java" matomo:"java"`
	Director    *bool `json:"dir" matomo:"dir"`
	Quicktime   *bool `json:"qt" matomo:"qt"`
	RealPlayer  *bool `json:"realp" matomo:"realp"`
	PDF         *bool `json:"pdf" matomo:"pdf"`
	WMA         *bool `json:"wma" matomo:"wma"`
	Gears       *bool `json:"gears" matomo:"gears"`
	Silverlight *bool `json:"ag" matomo:"ag"`
}

UserPlugins is a sub-struct of capabilities for a user

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.