From 8bcc788c0e45ab79e0f4ce80cda3363bb4588399 Mon Sep 17 00:00:00 2001 From: Grégoire Aubert Date: Thu, 23 May 2019 09:04:02 +0200 Subject: SONAR-12109 Web Analytics plugins (#1652) --- .../java/org/sonar/api/server/ws/WebService.java | 2 +- .../main/java/org/sonar/api/web/WebAnalytics.java | 136 +++++++++++++++++++++ 2 files changed, 137 insertions(+), 1 deletion(-) create mode 100644 sonar-plugin-api/src/main/java/org/sonar/api/web/WebAnalytics.java (limited to 'sonar-plugin-api') diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/server/ws/WebService.java b/sonar-plugin-api/src/main/java/org/sonar/api/server/ws/WebService.java index 4119270f1f3..0ac828699c4 100644 --- a/sonar-plugin-api/src/main/java/org/sonar/api/server/ws/WebService.java +++ b/sonar-plugin-api/src/main/java/org/sonar/api/server/ws/WebService.java @@ -71,7 +71,7 @@ import static java.util.Objects.requireNonNull; * .setHandler(new RequestHandler() { * {@literal @}Override * public void handle(Request request, Response response) { - * // read request parameters and generates response output + * // read request parameters and generate response output * response.newJsonWriter() * .beginObject() * .prop("hello", request.mandatoryParam("key")) diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/web/WebAnalytics.java b/sonar-plugin-api/src/main/java/org/sonar/api/web/WebAnalytics.java new file mode 100644 index 00000000000..2284b5c8651 --- /dev/null +++ b/sonar-plugin-api/src/main/java/org/sonar/api/web/WebAnalytics.java @@ -0,0 +1,136 @@ +/* + * SonarQube + * Copyright (C) 2009-2019 SonarSource SA + * mailto:info AT sonarsource DOT com + * + * This program is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public + * License as published by the Free Software Foundation; either + * version 3 of the License, or (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public License + * along with this program; if not, write to the Free Software Foundation, + * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + */ +package org.sonar.api.web; + +import org.sonar.api.ExtensionPoint; +import org.sonar.api.server.ServerSide; + +/** + * Extension point to support a web analytics tool like Matomo or + * Google Analytics in the webapp. + * + *

See the method {@link #getUrlPathToJs()} for the details about specification.

+ * + *

+ * Example of implementation with a {@link org.sonar.api.server.ws.WebService}: + *

+ * 
+ * import java.io.IOException;
+ * import java.io.OutputStream;
+ * import java.nio.charset.StandardCharsets;
+ * import org.apache.commons.io.IOUtils;
+ * import org.sonar.api.server.ws.Request;
+ * import org.sonar.api.server.ws.RequestHandler;
+ * import org.sonar.api.server.ws.Response;
+ * import org.sonar.api.server.ws.WebService;
+ * import org.sonar.api.web.WebAnalytics;
+ *
+ * public class MyWebAnalytics implements WebAnalytics, WebService, RequestHandler {
+ *
+ *   {@literal @}Override
+ *   public String getUrlPathToJs() {
+ *     return "api/myplugin/analytics";
+ *   }
+ *
+ *   {@literal @}Override
+ *   public void define(Context context) {
+ *     NewController controller = context.createController("api/myplugin");
+ *     controller.createAction("analytics")
+ *       .setInternal(false)
+ *       .setHandler(this);
+ *     controller.done();
+ *   }
+ *
+ *   {@literal @}Override
+ *   public void handle(Request request, Response response) throws IOException {
+ *     try (OutputStream output = response.stream()
+ *       .setMediaType("application/javascript")
+ *       .output()) {
+ *       IOUtils.write("{replace with the javascript content}", output, StandardCharsets.UTF_8);
+ *     }
+ *   }
+ * }
+ *
+ * + * @since 7.8 + */ +@ServerSide +@ExtensionPoint +public interface WebAnalytics { + + /** + * Returns the URL path to the Javascript file that will be loaded by the webapp. File must be + * provided by SonarQube server and can't be located outside. + * + *

+ * The returned path must not start with a slash '/' and must not contain ".." or "://". + *

+ * + *

+ * Examples: + *

+ *

+ * + *

+ * Webapp does not load the Javascript file if the URL does not return HTTP code 200. + *

+ * + *

+ * The Javascript file is composed of two parts: + *

+ *

+ * Example for Matomo: + * + * 
+   * var _paq = window._paq || [];
+   * // tracker methods like "setCustomDimension" should be called before "trackPageView"
+   * _paq.push(["trackPageView"]);
+   * _paq.push(["enableLinkTracking"]);
+   * (function() {
+   *   var u = "https://me.matomo.cloud/";
+   *   _paq.push(["setTrackerUrl", u + "matomo.php"]);
+   *   _paq.push(["setSiteId", "12345"]);
+   *   var d = document,
+   *     g = d.createElement("script"),
+   *     s = d.getElementsByTagName("script")[0];
+   *   g.type = "text/javascript";
+   *   g.async = true;
+   *   g.defer = true;
+   *   g.src = "//cdn.matomo.cloud/me.matomo.cloud/matomo.js";
+   *   s.parentNode.insertBefore(g, s);
+   * })();
+   *
+   * window.setWebAnalyticsPageChangeHandler(function(pathname) {
+   *   _paq.push(["setCustomUrl", pathname]);
+   *   _paq.push(["setDocumentTitle", document.title]);
+   *   _paq.push(["trackPageView"]);
+   * });
+   *
+ */ + String getUrlPathToJs(); + +} -- cgit v1.2.3