mapzen map scarab

Branding, social sharing, and tracking UI component for standalone demos.

NOTE: Standalone usage is deprecated.

This module was originally called a “bug,” a term borrowed from broadcast television (officially, “digital on-screen graphic”) where a show is branded in the lower corner to identify the broadcast network. Because of the other meaning of “bug” in computing, this is now called scarab.

NOTE: We have updated this to display the current brand imagery of Mapzen.

The scarab is designed for the following functionality:

Branding: Show the Mapzen attribution and provide a link to our website.
Sharing: Provide UI for viewers to easily share via social networks.
Tracking: Tracks interactions through Google Analytics.

This is as a standalone, drop-in JavaScript “library”. It has no hard dependencies (jQuery is not required) and should work on all modern browsers and IE9+ at minimum, although in practice, the demos will be driving the minimum compatibility of the page.

Including the scarab (deprecated)

Standalone JS is not currently published.

Instantiate the scarab in JavaScript:

var scarab = new MapzenScarab();

The scarab works without any additional configuration, but you can customize its behavior with by passing in an object like so:

var scarab = new MapzenScarab({
  name: 'Tangram',
  link: 'https://mapzen.com/projects/',
  tweet: 'Wow, what a cool WebGL map renderer by @mapzen!',
  repo: 'https://github.com/tangrams/tangram/',
  description: 'Here is a description of this scene!'
});

Basic options

These 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 and pre-populating tweets.
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. (see below)
repo	(none)	String. URL to source code repository. This should be a valid absolute URL. The logo is the GitHub logo but it won't magically prepend the GitHub domain for you. This button only appears if a URL is provided.
description	(none)	String. A text description of the scene. This button only appears if a description is provided. When clicked, the button displays a popup box below the scarab.

Advanced options

key	default value	description
analytics	true	Boolean. Whether to send custom tracking events to Google Analytics for this demo. Set to false to prevent this demo from sending events or loading Google Analytics (if not already present). If Google Analytics is loaded separately, it behaves normally (as if the bug is not there).

Features

Automatic iframe detection

The scarab 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 scarab will send custom tracking events to it.

If Google Analytics is not detected on the page, the scarab will insert Google Analytics, reporting to the Mapzen website's analytics property.

You can use the options property analytics: false to disable event tracking or loading a fallback Analytics.

The following events are currently tracked:

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

Custom styling

The scarab loads an external stylesheet. Elements created by the scarab have class names attached (prefixed in the .mz-bug-* namespace), so you can override the preset styles if you wish. However, this is generally discouraged since we can't guarantee that class names or styles will be backwards-compatible forever.

Social network sharing

Currently, sharing functionality is borrowed from RRSSB, the library used to create the social sharing buttons used on the Mapzen blog.

Twitter

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!"

Tweets automatically include the viewer's current URL (including hash data), so there is no need to provide this yourself.

Facebook

Facebook sharing is currently done via “sharer.php” which is actually their legacy endpoint for sharing things. (Normally, they would require an app id, which is difficult to set up for each individual demo.) Unfortunately, it's not very “smart.” So there is no pre-populated Facebook sharing message, for example.

It will automatically link to the viewer's current URL (including hash data).

If you want to customize the image, title, and description that appears in the Facebook post, you will need to add OpenGraph meta tags into the head of your demo page. Read the Facebook documentation for more information.

Other sharing options

Other sharing options are not currently planned.

Building

There is no build process for this. Please import and conduct minification etc. downstream.

mapzen / scarab