flutter_matomo源码解析

本文通过对flutter_matomo提供的对外API接口，了解能用它来实现哪些功能

相关资料

• 代码仓库
  • flutter_matomo
  • matomo
  • matomo--sdk-ios
  • matomo-sdk-android
• matomo官网
• matomo开发者网站

flutter_matmo接口解析

以下方法都是flutter项目中所能使用的matomo方法

• 初始化SDK

/// 参数url: matomo部署的服务器路径（如：https://YOUR_URL/piwik.php）
/// 参数siteId 在matomo客户端中设置的用于flutter客户端的站点ID
static Future<String> initializeTracker(String url, int siteId);

• 追踪屏幕

/// 参数widgetName 页面名称(如：登录页、首页、个人中心等等)
/// 参数eventName 定义事件名称(如：进入页面、离开页面)
static Future<String> trackScreenWithName(String widgetName, String eventName)

• 追踪事件

/// 参数widgetName 触发事件的入口(如登录按钮、定义按钮、分享按钮等等)
/// 参数eventName 事件名称(如登录事件、订阅事件、分享事件、开启定时关闭事件等等)
/// 参数eventAction 事件动作(可以传入该事件相关的一系列数据，如登录事件中的用户名、密码、登录时间、设备等等)
static Future<String> trackEventWithName(String widgetName, String eventName, String eventAction)

• 跟踪应用下载（仅在ANDROID上）

///官方解释，大意是记录app的下载次数，一般情况下一个设备上每个版本只记录一次
    /**
     * Sends a download event for this app.
     * This only triggers an event once per app version unless you force it.<p>
     * {@link Download#force()}
     * <p class="note">
     * Resulting download url:<p>
     * Case {@link org.matomo.sdk.extra.DownloadTracker.Extra.ApkChecksum}:<br>
     * http://packageName:versionCode/apk-md5-checksum<br>
     * <p>
     * Case {@link org.matomo.sdk.extra.DownloadTracker.Extra.None}:<br>
     * http://packageName:versionCode<p>
     *
     * @return this object, to chain calls.
     */
static Future<String> trackDownload();

• 根据ID追踪目标

///官方解释，大意是在matomo客户端中设置一个特定目标ID, 客户端在触发这个目标时，调用该方法，传入该ID
    /**
     * By default, Goals in Matomo are defined as "matching" parts of the screen path or screen title.
     * In this case a conversion is logged automatically. In some situations, you may want to trigger
     * a conversion manually on other types of actions, for example:
     * when a user submits a form
     * when a user has stayed more than a given amount of time on the page
     * when a user does some interaction in your Android application
     *
     * @param idGoal id of goal as defined in matomo goal settings
     */
static Future<String> trackGoal(int goalId)

扩展

以下是flutter_matomo中未实现的一些原生端matomo功能

matomo-android-sdk

• 追踪链接点击

/**
     * Tracks an  <a href="http://matomo.org/faq/new-to-matomo/faq_71/">Outlink</a>
     *
     * @param url HTTPS, HTTP and FTPare valid
     * @return this Tracker for chaining
     */
    public Outlink outlink(URL url);

• 追踪搜索功能

/**
     * Tracks an  <a href="http://matomo.org/docs/site-search/">site search</a>
     *
     * @param keyword Searched query in the app
     * @return this Tracker for chaining
     */
     public Search search(String keyword);

• 追踪印象(可以设置三个参数contentName、contentPiece、contentTarget)

官方解释和举例

• @param contentName The name of the content. For instance 'Ad Foo Bar'
• @param contentPiece The actual content. For instance the path to an image, video, audio, any text
• @param contentTarget The target the content leading to when an interaction occurs. For instance the URL of a landing page

/**
     * Tracking the impressions
     *
     * @param contentName The name of the content. For instance 'Ad Foo Bar'
     */
    public ContentImpression impression(String contentName)

• 追踪交互(可以设置四个参数contentInteraction、contentName、contentPiece、contentTarget，并且contentName和contentPiece要和追踪印象保持一致)

官方解释和举例

• @param contentInteraction The name of the interaction with the content. For instance a 'click'
• @param contentName The name of the content. For instance 'Ad Foo Bar'
• @param contentPiece The actual content. For instance the path to an image, video, audio, any text
• @param contentTarget The target the content leading to when an interaction occurs. For instance the URL of a landing page

/**
     * Tracking the interactions<p>
     * To map an interaction to an impression make sure to set the same value for contentName and contentPiece as
     * the impression has.
     *
     * @param contentInteraction The name of the interaction with the content. For instance a 'click'
     * @param contentName        The name of the content. For instance 'Ad Foo Bar'
     */
    public ContentInteraction interaction(String contentName, String contentInteraction)

• 追踪购物车

 /**
     * Tracks a shopping cart. Call this javascript function every time a user is adding, updating
     * or deleting a product from the cart.
     *
     * @param grandTotal total value of items in cart
     */
    public CartUpdate cartUpdate(int grandTotal)

• 追踪订单

/**
    * Tracks an Ecommerce order, including any ecommerce item previously added to the order.  All
    * monetary values should be passed as an integer number of cents (or the smallest integer unit
    * for your currency)
    *
    * @param orderId    (required) A unique string identifying the order
    * @param grandTotal (required) total amount of the order, in cents
    */
   public Order order(String orderId, int grandTotal) 

• 追踪异常（并非捕捉异常，只是在一些可能出现问题的地方，使用该方法记录异常发生了）

/**
     * Caught exceptions are errors in your app for which you've defined exception handling code,
     * such as the occasional timeout of a network connection during a request for data.
     * <p>
     * This is just a different way to define an event.
     * Keep in mind Matomo is not a crash tracker, use this sparingly.
     * <p>
     * For this to be useful you should ensure that proguard does not remove all classnames and line numbers.
     * Also note that if this is used across different app versions and obfuscation is used, the same exception might be mapped to different obfuscated names by proguard.
     * This would mean the same exception (event) is tracked as different events by Matomo.
     *
     * @param throwable exception instance
     */
    public Exception exception(Throwable throwable)

• 捕捉并追踪异常（会把旧版本中存在的新版本已经修复的异常的追踪过来）

/**
     * This will create an exception handler that wraps any existing exception handler.
     * Exceptions will be caught, tracked, dispatched and then rethrown to the previous exception handler.
     * <p>
     * Be wary of relying on this for complete crash tracking..
     * Think about how to deal with older app versions still throwing already fixed exceptions.
     * <p>
     * See discussion here: https://github.com/matomo-org/matomo-sdk-android/issues/28
     */
    public UncaughtExceptions uncaughtExceptions()

• 开启自动追踪页面事件（不适用于flutter）

/**
     * This method will bind a tracker to your application,
     * causing it to automatically track Activities with {@link #screen(Activity)} within your app.
     *
     * @param app your app
     * @return the registered callback, you need this if you wanted to unregister the callback again
     */
    @TargetApi(Build.VERSION_CODES.ICE_CREAM_SANDWICH)
    public AppTracking screens(Application app)