nagai/fune
3
0
Fork 0
forked from mirrors/gecko-dev
Code Pull requests Activity
fune/mobile/android/android-components/components/service/pocket/README.md
Mugurell 86af95d120 [components] For https://github.com/mozilla-mobile/android-components/issues/12184 - Add support for pacing and rotating sponsored Pocket stories 
Stories can be paced and rotated based on the properties received in the
endpoint response.

Since rotating involves a limit of impressions in a certain period I've added
a new table for keeping only this timestamps while the effective limits will be
held in the sponsored stories table.

With very little time between this and the previous patch which added support
for sponsored stories I've skipped created a new database version and sticked
to using version 2 again to ensure a smoother migration when this feature gets
to the users.

Possibly because of the foreignKey addition the migration could not be tested
in the JVM (because of sqlite exceptions coming from robolectric) and so I
switched testing this to a real device.
2022-05-26 06:17:10 +00:00

2.5 KiB
Raw Blame History

Android Components > Service > Pocket

A library for easily getting Pocket recommendations that transparently handles downloading, caching and periodically refreshing Pocket data.

Currently this supports:

  • Pocket recommended stories.
  • Pocket sponsored stories.

Usage

  1. For Pocket recommended stories:

    • Use PocketStoriesService#startPeriodicStoriesRefresh and PocketStoriesService#stopPeriodicStoriesRefresh as high up in the client app as possible (preferably in the Application object or in a single Activity) to ensure the background story refresh functionality works for the entirety of the app lifetime.
    • Use PocketStoriesService.getStories to get the current list of Pocket recommended stories.

  2. For Pocket sponsored stories:

    • Use PocketStoriesService#startPeriodicSponsoredStoriesRefresh and PocketStoriesService#stopPeriodicSponsoredStoriesRefresh as high up in the client app as possible (preferably in the Application object or in a single Activity) to ensure the background story refresh functionality works for the entirety of the app lifetime.
    • Use PocketStoriesService.getSponsoredStories to get the current list of Pocket recommended stories.
    • Use PocketStoriesService,recordStoriesImpressions to try and persist that a list of sponsored stories were shown to the user. (Safe to call even if those stories are not persisted).
    • Use PocketStoriesService.deleteProfile to delete all server stored information about the device to which sponsored stories were previously downloaded. This may include data like network ip and application tokens.
    Pacing and rotating:

    A new PocketSponsoredStoryCaps is available in the response from PocketStoriesService.getSponsoredStories which allows checking currentImpressions, lifetimeCount, flightCount, flightPeriod based on which the client can decide which stories to show. All this is based on clients calling PocketStoriesService,recordStoriesImpressions to record new impressions in between application restarts.

Setting up the dependency

Use Gradle to download the library from maven.mozilla.org (Setup repository):

implementation "org.mozilla.components:service-pocket:{latest-version}"

License

This Source Code Form is subject to the terms of the Mozilla Public
License, v. 2.0. If a copy of the MPL was not distributed with this
file, You can obtain one at http://mozilla.org/MPL/2.0/