Attribution "bug" design document

louh commented 9 years ago

Work in progress.

Overview

We make demo pages that are meant to be iframed into other pages. Sometimes they go viral. When this happens, the demo map is often linked to directly, and most viewers have no way of coming back to a Mapzen page to learn more. We need a way to brand demo pages when viewed out of context.

The term "bug" used here is borrowed from broadcast television (officially, "digital on-screen graphic") where a show is branded in the lower corner to identify the broadcast network. The other meaning of "bug" in computing might make this not a great term to use in the long run.

The main goals for the bug:

Identify that the demo is powered by Mapzen and provide a link back to us (or the product page, etc.)
Provide a way to easily share via social networks to drive up each demo's viral capacity.
Design mockups
Square corners, social icons highlight with underline (closer to navbar of current site)
Alternate: rounded corners, social icons inside circles (more generic)

These mockups show intent, they are not meant to be pixel perfect representations.

There will only be one canonical "official" stylesheet. Custom CSS to override the preset styles are available if you really want to.

Implementation

The "bug" is designed as a standalone, drop-in JavaScript "library". It has no other hard dependencies (jQuery is not required) and should work on modern browsers and IE9+ at minimum, although in practice compatibility would be largely driven by the demo itself. Since it is served from the RawGit CDN, updates to the bug can propagate to all demo pages that use it. (There is a cache time on RawGit. You can refer to commits directly instead of the master branch to lock the bug to a specific version, but this means you'll need to manually upgrade it in the future.)

<!-- Mapzen bug UI component -->
<script src='https://cdn.rawgit.com/mapzen/ui/0.1.1/components/bug/bug.js'></script>

Instantiate the bug:

var mzBug = new MapzenBug();

You pay pass in an optional object with options:

var mzBug = new MapzenBug({
  name: 'Tangram',
  link: 'https://github.com/tangrams/tangram/',
  tweet: 'Wow, what a cool demo by @mapzen!'
});

All options are optional. Defaults will be provided if not set.

key	default value	description
link	'https://mapzen.com/'	String. URL to go to when viewer clicks on the Mapzen logo. This should be a valid absolute URL.
name	'Mapzen demo'	String. Name of the demo or product. This will be used in analytics tracking.
analytics	true	Boolean. Whether to send custom tracking events to Google Analytics for this demo. Set to false to prevent this demo from sending custom events even if GA is present (but GA will still track page views and other default behavior that is not part of the bug functionality).
tweet	(depends)	String. Set a custom pre-written tweet message. The current URL of the page will be automatically appended to the end of the message. If not included, a default tweet (based on the name option, if provided) will be used.

Automatic iframe detection

The bug detects if the page being viewed is in an iframe or not. If it is in an iframe, it naively assumes that its parent page is giving the demo proper context, so its script stops executing immediately and does nothing else.

Google Analytics event tracking

If Google Analytics is detected on the page, the bug will send custom tracking events to it.

If Google Analytics is not detected on the page, the bug will insert Mapzen's default Analytics code which will report back to the Mapzen website analytics property. This detection occurs some amount of milliseconds after the page is done loading to allow other Analytics code, if present, to load first.

The following events are tracked:

The bug is active (that is, the viewer has opened this page outside of an iframe)
If the bug is loading its own Analytics property
The viewer has clicked the Mapzen logo (which opens the URL)
The viewer has clicked the Twitter icon
The viewer has clicked the Facebook icon

More info TBD

Custom styling

Styling is provided either via DOM scripting or an external stylesheet (actual implementation TBD). DOM scripting means an external file won't need to be loaded (so it's slightly faster). An external stylesheet will be easier to override with custom styles, and is easier and more flexible to maintain, but requires an additional HTTP request.

Class names are provided to DOM elements generated by the bug script, prefixed in the mz-bug-* namespace. Custom styles overriding the bug styles should be generally discouraged as much as possible because there's no guarantee that class names or styles will be backwards-compatible forever. -- but because someone is bound to ask, yes, it is possible to override the styles.

Twitter (phase 1)

Twitter functionality should be similar to how it works on the blog (via RRSSB).

You may specify what the pre-filled tweet message is with the tweet option. If you don't set it, the default values are:

If the name option is set, the pre-filled tweet is "name, powered by @mapzen"
If the name option is not set, the pre-filled tweet is "Check out this demo by @mapzen!"

All tweets will also automatically include the current URL of the page.

Facebook (phase 2)

Facebook functionality should be similar to how it works on the blog (via RRSSB).

Other sharing options (phase 3)

Other sharing options may be added in the future.

souperneon commented 9 years ago

@louh square please (no rounded corners for us at this time!) I'd like to play with the interaction a little bit to get a better feel

louh commented 9 years ago

:+1: square corners it is.

louh commented 9 years ago

@souperneon UI as of today: http://louhuang.com/simple-demo/#15/40.7364/-73.9751 (

mapzen / ui