Custom dimensions

Independant custom dimension

// TrackHelper class
    public Dimension dimension(int id, String value) {
        return new Dimension(mBaseTrackMe).dimension(id, value);
    }

    public static class Dimension extends TrackHelper {
        // TrackMe - track event that is collected by dispatcher and send to server
        Dimension(TrackMe base) {
            super(base);
        }

        @Override
        public Dimension dimension(int id, String value) {
            CustomDimension.setDimension(mBaseTrackMe, id, value);
            return this;
        }
    }
    
    
    /**
 * Allows you to track Custom Dimensions.
 * In order to use this functionality install and configure
 * https://plugins.piwik.org/CustomDimensions plugin.
 */
public class CustomDimension {
    private static final String LOGGER_TAG = Piwik.LOGGER_PREFIX + "CustomDimension";

    /**
     * This method sets a tracking API parameter dimension%dimensionId%=%dimensionValue%.
     * Eg dimension1=foo or dimension2=bar.
     * So the tracking API parameter starts with dimension followed by the set dimensionId.
     * <p>
     * Requires <a href="https://plugins.piwik.org/CustomDimensions">Custom Dimensions</a> plugin (server-side)
     *
     * @param trackMe        into which the data should be inserted
     * @param dimensionId    accepts values greater than 0
     * @param dimensionValue is limited to 255 characters, you can pass null to delete a value
     * @return true if the value was valid
     */
    public static boolean setDimension(@NonNull TrackMe trackMe, int dimensionId, @Nullable String dimensionValue) {
        if (dimensionId < 1) {
            Timber.tag(LOGGER_TAG).e("dimensionId should be great than 0 (arg: %d)", dimensionId);
            return false;
        }
        if (dimensionValue != null && dimensionValue.length() > 255) {
            dimensionValue = dimensionValue.substring(0, 255);
            Timber.tag(LOGGER_TAG).w("dimensionValue was truncated to 255 chars.");
        }
        if (dimensionValue != null && dimensionValue.length() == 0) {
            dimensionValue = null;
        }
        trackMe.set(formatDimensionId(dimensionId), dimensionValue);
        return true;
    }

    @Nullable
    public static String getDimension(TrackMe trackMe, int dimensionId) {
        return trackMe.get(formatDimensionId(dimensionId));
    }

    private static String formatDimensionId(int id) {
        return "dimension" + id;
    }
}

Screen custom dimension

   /**
     * Calls {@link #screen(String)} for an activity.
     * Uses the activity-stack as path and activity title as names.
     *
     * @param activity the activity to track
     */
    public Screen screen(Activity activity) {
        String breadcrumbs = ActivityHelper.getBreadcrumbs(activity);
        return new Screen(this, ActivityHelper.breadcrumbsToPath(breadcrumbs)).title(breadcrumbs);
    }

    public static class Screen extends BaseEvent {
        private final String mPath;
        private final CustomVariables mCustomVariables = new CustomVariables();
        private final Map<Integer, String> mCustomDimensions = new HashMap<>();
        private String mTitle;

        Screen(TrackHelper baseBuilder, String path) {
            super(baseBuilder);
            mPath = path;
        }

        /**
         * The title of the action being tracked. It is possible to use slashes / to set one or several categories for this action.
         *
         * @param title Example: Help / Feedback will create the Action Feedback in the category Help.
         * @return this object to allow chaining calls
         */
        public Screen title(String title) {
            mTitle = title;
            return this;
        }

        /**
         * Requires <a href="https://plugins.piwik.org/CustomDimensions">Custom Dimensions</a> plugin (server-side)
         *
         * @param index          accepts values greater than 0
         * @param dimensionValue is limited to 255 characters, you can pass null to delete a value
         */
        public Screen dimension(int index, String dimensionValue) {
            mCustomDimensions.put(index, dimensionValue);
            return this;
        }

        /**
         * Custom Variable valid per screen.
         * Only takes effect when setting prior to tracking the screen view.
         *
         * @see CustomDimension and {@link #dimension(int, String)}
         * @deprecated Consider using <a href="http://piwik.org/docs/custom-dimensions/">Custom Dimensions</a>
         */
        @Deprecated
        public Screen variable(int index, String name, String value) {
            mCustomVariables.put(index, name, value);
            return this;
        }

        @Nullable
        @Override
        public TrackMe build() {
            if (mPath == null) return null;
            final TrackMe trackMe = new TrackMe(getBaseTrackMe())
                    .set(QueryParams.URL_PATH, mPath)
                    .set(QueryParams.ACTION_NAME, mTitle);
            if (mCustomVariables.size() > 0) {
                //noinspection deprecation
                trackMe.set(QueryParams.SCREEN_SCOPE_CUSTOM_VARIABLES, mCustomVariables.toString());
            }
            for (Map.Entry<Integer, String> entry : mCustomDimensions.entrySet()) {
                CustomDimension.setDimension(trackMe, entry.getKey(), entry.getValue());
            }
            return trackMe;
        }
    }

Tests

    @Test
    public void testSetScreenCustomDimension() throws Exception {
        TrackHelper.track()
                .screen("")
                .dimension(1, "dim1")
                .dimension(2, "dim2")
                .dimension(3, "dim3")
                .dimension(3, null)
                .dimension(4, null)
                .with(mTracker);

        verify(mTracker).track(mCaptor.capture());
        assertEquals("dim1", CustomDimension.getDimension(mCaptor.getValue(), 1));
        assertEquals("dim2", CustomDimension.getDimension(mCaptor.getValue(), 2));
        assertNull(CustomDimension.getDimension(mCaptor.getValue(), 3));
        assertNull(CustomDimension.getDimension(mCaptor.getValue(), 4));
    }

    @Test
    public void testCustomDimension_trackHelperAny() {
        TrackHelper.track()
                .dimension(1, "visit")
                .dimension(2, "screen")
                .event("category", "action")
                .with(mTracker);

        verify(mTracker).track(mCaptor.capture());
        assertEquals("visit", CustomDimension.getDimension(mCaptor.getValue(), 1));
        assertEquals("screen", CustomDimension.getDimension(mCaptor.getValue(), 2));
        assertEquals("category", mCaptor.getValue().get(QueryParams.EVENT_CATEGORY));
        assertEquals("action", mCaptor.getValue().get(QueryParams.EVENT_ACTION));
    }

    @Test
    public void testCustomDimension_override() {
        TrackHelper.track()
                .dimension(1, "visit")
                .dimension(2, "screen")
                .screen("/path")
                .dimension(1, null)
                .with(mTracker);

        verify(mTracker).track(mCaptor.capture());
        assertNull(CustomDimension.getDimension(mCaptor.getValue(), 1));
        assertEquals("screen", CustomDimension.getDimension(mCaptor.getValue(), 2));
        assertEquals("/path", mCaptor.getValue().get(QueryParams.URL_PATH));
    }