diff --git a/.github/workflows/generate-docs.yml b/.github/workflows/generate-docs.yml deleted file mode 100644 index f55147c..0000000 --- a/.github/workflows/generate-docs.yml +++ /dev/null @@ -1,37 +0,0 @@ -name: Generate and publish documentation - -on: - release: - types: [ released ] - workflow_dispatch: - -# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages -permissions: - contents: read - pages: write - id-token: write - -jobs: - deploy: - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - name: set up JDK - uses: actions/setup-java@v3 - with: - java-version: '17' - distribution: 'temurin' - - name: Generate API documentation - run: ./gradlew dokkaHtml - - name: Setup Pages - uses: actions/configure-pages@v4 - - name: Upload artifact - uses: actions/upload-pages-artifact@v3 - with: - path: 'parsely/build/dokka/html' - - name: Deploy to GitHub Pages - id: deployment - uses: actions/deploy-pages@v4 diff --git a/parsely/src/main/java/com/parsely/parselyandroid/ParselyTracker.kt b/parsely/src/main/java/com/parsely/parselyandroid/ParselyTracker.kt index e6adbe8..3ee7a63 100644 --- a/parsely/src/main/java/com/parsely/parselyandroid/ParselyTracker.kt +++ b/parsely/src/main/java/com/parsely/parselyandroid/ParselyTracker.kt @@ -21,21 +21,20 @@ import org.jetbrains.annotations.TestOnly /** * Tracks Parse.ly app views in Android apps * - * Accessed as a singleton. Maintains a queue of pageview events in memory and periodically + * Accessed as a singleton. Maintains a queue of events in memory and periodically * flushes the queue to the Parse.ly pixel proxy server. */ public interface ParselyTracker { /** - * Register a pageview event using a URL and optional metadata. + * Register a pageview event using a URL and optional metadata. You should only call this method once per page view. * - * @param url The URL of the article being tracked - * (eg: "http://example.com/some-old/article.html") - * @param urlRef Referrer URL associated with this video view. + * @param url The URL of the article being tracked (eg: "http://example.com/some-old/article.html") + * @param urlRef The url of the page that linked to the viewed page. Analogous to HTTP referer * @param urlMetadata Optional metadata for the URL -- not used in most cases. Only needed - * when `url` isn't accessible over the Internet (i.e. app-only - * content). Do not use this for **content also hosted on** URLs Parse.ly - * would normally crawl. + * when `url` isn't accessible over the Internet (i.e. app-only + * content). Do not use this for **content also hosted on** URLs Parse.ly + * would normally crawl. * @param extraData A Map of additional information to send with the event. */ public fun trackPageview( @@ -48,13 +47,18 @@ public interface ParselyTracker { /** * Start engaged time tracking for the given URL. * + * Start engaged time tracking for the given URL. Once called, the Parse.ly tracking script + * will automatically send `heartbeat` events periodically to capture engaged time for this url + * until engaged time tracking stops. * - * This starts a timer which will send events to Parse.ly on a regular basis - * to capture engaged time for this URL. The value of `url` should be a URL for - * which `trackPageview` has been called. + * This call also automatically stops tracking engaged time for any urls that are not + * the current url. * - * @param url The URL to track engaged time for. - * @param urlRef Referrer URL associated with this video view. + * The value of `url` should be a URL for which [trackPageview] has been called. + * + * @param url The URL of the tracked article (eg: “http://example.com/some-old/article.html“) + * @param urlRef The url of the page that linked to the page being engaged with. Analogous to HTTP referer + * @param extraData A map of additional information to send with the generated `heartbeat` events */ public fun startEngagement( url: String, @@ -63,38 +67,36 @@ public interface ParselyTracker { ) /** - * Stop engaged time tracking. - * - * * Stops the engaged time tracker, sending any accumulated engaged time to Parse.ly. - * NOTE: This **must** be called in your `MainActivity` during various Android lifecycle events - * like `onPause` or `onStop`. Otherwise, engaged time tracking may keep running in the background - * and Parse.ly values may be inaccurate. + * + * NOTE: This **must** be called during various Android lifecycle events like + * `onPause` or `onStop`. Otherwise, engaged time tracking may keep running + * in the background and Parse.ly values may be inaccurate. */ public fun stopEngagement() /** * Start video tracking. * - * - * Starts tracking view time for a video being viewed at a given url. Will send a `videostart` - * event unless the same url/videoId had previously been paused. + * This starts tracking view time for a video that someone is watching at a given url. + * It will send a `videostart` event unless the same url/videoId had previously been paused. * Video metadata must be provided, specifically the video ID and video duration. * - * * The `url` value is *not* the URL of a video, but the post which contains the video. If the video * is not embedded in a post, then this should contain a well-formatted URL on the customer's - * domain (e.g. http:///app-videos). This URL doesn't need to return a 200 status + * domain (e.g. http://example.com/app-videos). This URL doesn't need to return a 200 status * when crawled, but must but well-formatted so Parse.ly systems recognize it as belonging to * the customer. * - * @param url URL of post the video is embedded in. If videos is not embedded, a - * valid URL for the customer should still be provided. - * (e.g. http:///app-videos) - * @param urlRef Referrer URL associated with this video view. - * @param videoMetadata Metadata about the video being tracked. - * @param extraData A Map of additional information to send with the event. - */ + * If a video is already being tracked when this method is called, unless it's the same video, + * the existing video tracking will be stopped and a new `videostart` event will be sent for the new video. + * + * @param url URL of post with the embedded video. If you haven’t embedded the video, + * then send a valid URL matching your domain. (e.g. http://example.com/app-videos) + * @param urlRef The url of the page that linked to the page being engaged with. Analogous to HTTP referer + * @param videoMetadata Metadata about the tracked video + * @param extraData A Map of additional information to send with the event + */ public fun trackPlay( url: String, urlRef: String = "", @@ -103,30 +105,23 @@ public interface ParselyTracker { ) /** - * Pause video tracking. + * Pause video tracking for an ongoing video. If [trackPlay] is immediately called again + * for the same video, a new `videostart` event will not be sent. This models a user pausing + * a playing video. * * - * Pauses video tracking for an ongoing video. If [.trackPlay] is immediately called again for - * the same video, a new video start event will not be sent. This models a user pausing a - * playing video. - * - * - * NOTE: This or [.resetVideo] **must** be called in your `MainActivity` during various Android lifecycle events + * NOTE: This or [resetVideo] **must** be called during various Android lifecycle events * like `onPause` or `onStop`. Otherwise, engaged time tracking may keep running in the background * and Parse.ly values may be inaccurate. */ public fun trackPause() /** - * Reset tracking on a video. - * - * - * Stops video tracking and resets internal state for the video. If [.trackPlay] is immediately - * called for the same video, a new video start event is set. This models a user stopping a - * video and (on [.trackPlay] being called again) starting it over. - * + * Stops video tracking and resets internal state for the video. + * If [trackPlay] is immediately called for the same video, a new `videostart` event is set. + * This models a user stopping a video and (on [trackPlay] being called again) starting it over. * - * NOTE: This or [.trackPause] **must** be called in your `MainActivity` during various Android lifecycle events + * NOTE: This or [trackPause] **must** be called during various Android lifecycle events * like `onPause` or `onStop`. Otherwise, engaged time tracking may keep running in the background * and Parse.ly values may be inaccurate. */ @@ -143,13 +138,16 @@ public interface ParselyTracker { } /** - * Singleton instance factory Note: this must be called before [.sharedInstance] + * Singleton instance factory. This **must** be called before [sharedInstance] + * If this method is called when an instance already exists, a [ParselyAlreadyInitializedException] will be thrown. * - * @param siteId The Parsely public site id (eg "example.com") + * + * @param siteId The Parsely public site id (eg "example.com") * @param flushInterval The interval at which the events queue should flush, in seconds - * @param context The current Android application context - * @param dryRun If set to `true`, events **won't** be sent to Parse.ly server - * @return The singleton instance + * @param context The current Android application context + * @param dryRun If set to `true`, events **won't** be sent to Parse.ly server + * @return The singleton instance + * @throws ParselyAlreadyInitializedException if the ParselyTracker instance is already initialized. */ @JvmStatic @JvmOverloads @@ -165,6 +163,15 @@ public interface ParselyTracker { instance = ParselyTrackerInternal(siteId, flushInterval, context, dryRun) } + /** + * Returns the singleton instance of the ParselyTracker. + * + * This method **must** be called after the [init] method. + * If the [init] method hasn't been called before this method, a [ParselyNotInitializedException] will be thrown. + * + * @return The singleton instance of ParselyTracker. + * @throws ParselyNotInitializedException if the ParselyTracker instance is not initialized. + */ @JvmStatic public fun sharedInstance(): ParselyTracker = ensureInitialized()