Improvements to the social media activity modules and content scripts

[jonathanmayer]

Terrific work @akohlbre putting together our social media activity functionality in https://github.com/citp/web-science/commit/cfc64ac4d72fab2fd81e1ebf5d27563158b17106. The pipeline in Utilities/SocialMediaActivity.js is elegant engineering—a bunch of messy HTTP(S) parsing turned into clean and clear abstractions. Suggestions below, the vast majority of which are minor.

• Studies/SocialMediaSharing.js

  • [ ] Rename the function filterTokensToUrls to be more descriptive
  • [ ] Add explanatory comments in the event handlers
  • [ ] Rename the module to better describe what it now does (e.g., SocialMediaLinkSharing)
  • [ ] Update the private window handling

• Studies/facebook.js

  • [ ] Move to Utilities/content-scripts/
  • [ ] Rename to clarify this is associated with the SocialMediaActivity module (e.g., socialMediaActivity-facebook.js)
  • [ ] Move the private browsing check to the start
  • [ ] Fix the module reference in the private window logic
  • [ ] Try to find a less fragile selector for identifying media boxes
  • [ ] Add comments and a message type for the browser.runtime.onMessage listener
  • [ ] Try to find a less fragile selector for identifying content in a reshared post

• Studies/twitter.js

  • See comment below moving this logic into the SocialMediaActivity module, which would be cleaner and let us get rid of this content script
  • [ ] Move to /Utilities/content-scripts/
  • [ ] Rename to clarify this is part of SocialMediaActivity (e.g., socialMediaActivity-twitter.js)
  • [ ] Add comments for the getTweetContent function
  • [ ] Drop the console.log
  • [ ] Add comments and a message type for the browser.runtime.onMessage listener
  • [ ] Drop the unused response (a holdover from the Facebook content script?)

• Utilities/SocialMediaActivity.js

  • [ ] Drop the WebScience import and add a Messaging import
  • [ ] Correct the debugLog import or remove it if unnecessary
  • [ ] Add module documentation explaining what is currently supported, what isn't, and why; the general architecture of the module; and the HTTP(S) request → verifier → extractor → completer (?) → listener pipeline
  • [ ] Add explanatory comments for the cryptic modules vars
  • [ ] Use camel case for the module vars for consistency
  • [ ] Add support for private windows
  • [ ] Revise the registerPlatformListener documentation to clarify what the function does (sets up an internal listener if necessary and saves the client callback) and that the function is internal to the module
  • [ ] Rename registerPlatformListener to match what the function does (e.g., registerActivityListenerAndStoreCallback)
  • [ ] Use a boolean rather than a string for the blocking parameter in registerPlatformListener (and associated logic) to avoid repetition in the other listener registration functions
  • [ ] Rename handler.stage for clarity (e.g., handler.webRequestStage)
  • [ ] Rename handler.urls for clarity (e.g., platformActivityUrls)
  • [ ] Standardize on the term "activity" or "event" or "action" throughout the module; I don't have much preference, just needs to be consistent
  • [ ] Add a JSDoc type definition for each event type
  • [ ] Add a JSDoc type definition for blocking callbacks
  • [ ] Add a JSDoc type definition for verification functions
  • [ ] Add a JSDoc type definition for extractor functions
  • [ ] Simplify the object construction in await verifier({..., await extractor({..., and completer({...
  • [ ] Remove the unnecessary Promise wrapper in handleGenericEvent
  • [ ] Add support for multiple blocking listeners per event type (the listener should get a flag if the event was cancelled by a different listener)
  • [ ] Use the term "listener", "handler", "callback", or "tracker" consistently in the module; I have a slight preference for "listener" since that's what we're using elsewhere and what appears in WebExtensions
  • [ ] Rename verifyPostReq for clarity (e.g., verifyPostRequest)
  • [ ] Merge platformHandlers and clientCallbacks to avoid repetition
  • [ ] Merge the event objects (e.g., platformHandlers.twitter.tweet) into the platformHandlers assignment to avoid repetition; for all the fields that are optional or initialize to null, you can also avoid repetition by iterating over the events once
  • [ ] Move the logic for getTweetContent into the module rather than message passing with a content script; unless I'm missing something, none of this logic requires a content script (but it might require setting aReferer header for a Twitter webpage)
  • [ ] Rename tweetContentInit for clarity
  • [ ] Add documentation to tweetContentInit explaining how it handles the scenario where the user hasn't yet logged into Twitter (i.e., it'll grab the relevant values as soon as the user logs in)
  • [ ] Rename fbPostContentInit for clarity
  • [ ] Add support for multiple Facebook timelines open in multiple tabs
  • [ ] Add logic for the user navigating away from or closing a tab with a Facebook timeline
  • [ ] Use relative paths for browser.contentScripts.register files
  • [ ] Use the term "reaction" rather than "react" for the Facebook event type (React is a Facebook JavaScript library)
  • [ ] For all the verification and extraction functions, add clearer documentation and fix the default parameters to avoid trying to reference a parameter on a null or setting a null time
  • [ ] Remove the completer step of the processing pipeline if it's not needed
  • [ ] Fix parseFacebookPost (unsure what's going on there, and looks like it belongs in a content script)
  • [ ] Rename requestPostContents to include Facebook
  • [ ] Use async functions rather than Promise returns for requestPostContents, getFacebookPostContents, and getRedditThingContents (since that's the style we've been generally using in other modules)
  • [ ] Use boolean for the verification function return values rather than null or { }

[jonathanmayer]

Migrated to the web-science repo.

• socialMediaLinkSharing.js: https://github.com/mozilla-rally/web-science/issues/17
• socialMediaActivity.facebook.content.js: https://github.com/mozilla-rally/web-science/issues/15
• socialMediaActivity.twitter.content.js: https://github.com/mozilla-rally/web-science/issues/15
• socialMediaActivity.js: https://github.com/mozilla-rally/web-science/issues/23