jryans/mobile.md

## mobile.md

      
    Raw
  

              mobile.md
            
          
    This is an opinionated technical design for our mobile strategy.  We can use this to frame our discussion and evolve it as new decisions are made.
What does "mobile" mean?

Mobile means a lot of different things to different people. It's really not just one extra case to consider. In the context of our visualizations, we should think about each of the following use cases:

Visualization embedded into client's responsive site:


Viewed on a desktop
Viewed on a tablet
Viewed on a smartphone


Visualization embedded into client's device-specific site:


Meant for desktops
Meant for tablets (haven't seen too many of these)
Meant for smartphones


Full screen visualization:


Viewed on a desktop
Viewed on a tablet
Viewed on a smartphone


Visualization as a part of native mobile app:


On Android
On iOS

That's a lot of situations, so for our first phase of mobile, let's ignore native apps until we can prove greater demand.
How can content behave differently per device?

The main techniques available to create a different experience per device are:

Create entirely separate sites
Use CSS media queries based on screen width, etc. and JS to alter behavior
Detect the device based on the user agent string

From a technical perspective, options 1 and 2 are feasible for us, though option 1 would result in multiple iframe URLs, which would need to be selected either manually by the client or detected by a JS embed library (described below).
Option 3 entails maintaining a database of user agent strings that mean "mobile" / "tablet".  This is quite error prone and requires a lot of maintenance.  While there are third parties would could pay for this data, it's really not an approach recommended by the front-end community:
Browser detection is not the way to go! - W3C

Option 2 strikes a good balance of allowing a single code base for engineers while still allowing content to vary.
So, we have to figure out 9 different modes for each product??

No. At most, there are really 6 modes (since embeds don't need to differ visually for client responsive vs. device-specific). Let's have design assemble comps for a popular product (e.g. stream) to get an idea if we truly need to act differently under all 6.
Today we barely use separate modes, and really only for full screen products.  If we really take advantage of the technique, we can change things like:

Sizing

Fonts
Avatars
Buttons


Appearance

Rearrange to single column on small width
Hide less important areas on small width
Stop floating giant headers and footers on small height


Interaction

Popups vs. overlays


If we just use media queries, all our embeds will think they are on tiny phones!

The issue here is that our embedded iframes only know how big their section of the page is.  They do not know they are potentially embedded within an large page viewed on a desktop.
We solve this by providing this information to the iframe.  With a JS embedding approach, we can provide important data to the iframe automatically (no client work):

Visualization is embedded (not full screen)
The outer page dimensions are W x H

That way we don't end up presenting e.g. comically large buttons to desktop users.
Device-specific sites

There is no way for us to detect that the client is using device-specific site.  However, let's allow them to pass that information to us.  Via our JS embedding API, they can indicate that we're on their phone / tablet site and then apply changes as necessary.
Look great by default

Without the client configuring anything special for mobile, we can offer great defaults for the entire spectrum of devices.
Product Configuration

As we described recently, we could create a "Mobile" section in the visualization config so the client can configure what avatar sizes we use on tablets vs. phones vs. desktops.
However, this would significantly increase the configuration complexity of each product.  The main issue we have on mobile is that we really have no optimized defaults today.  Let's focus on the best experience by default, and if we later hear that some client really does want to change 5 different settings for each device type, we can go down that road.
JS Embedding API

Today the main way clients embed our content is with an iframe tag we give them.  We can make this more powerful and flexible with JS API they use instead.  In the context mobile, this would be used to:

Measure outer page size and signal to an iframe
Allow clients to indicate we're on a device-specific site

However, it also serves as a foundation for other initiatives as well:

First-class analytics support
Level of indirection to simplify product upgrades

Current Embed

Currently we give clients the following:
<iframe 
    src="http://up.massrelevance.com/massrel-products/image-poll-2/index.html?config=jryans/image-poll-test" 
    frameborder="0" 
    width="500px" 
    height="800px" 
    style="border-top-style: none; border-right-style: none; border-bottom-style: none; border-left-style: none; border-width: initial; border-color: initial; border-image: initial; overflow-x: none; overflow-y: none;" 
    allowtransparency="true" 
    scrolling="auto"
></iframe>
Future Embed

In the future, we can have them add an API to their page:
<script src="//products.massrelevance.com/v1/api.js" type="text/javascript"></script>
Somewhere in their page, they'll create a container that acts as a placeholder for the iframe:
<div id="mr-image-poll" class="mr-product" data-product="jryans/image-poll-test"></div>
That's enough to get the product to appear, and many clients will probably stop there.
However, if they want to configure further settings, for example to signal that we're on a device specific site, they can either add more data to the container:
<div id="mr-image-poll" class="mr-product" data-product="jryans/image-poll-test" data-device="tablet"></div>
or write some JS:
MR.configureProduct({
  elem: "#mr-image-poll",
  device: "tablet"
});
The main options I'd envision to support the mobile effort are:

device: Signal a particular device-specific site
height / width: Override the height and width settings
aspectRatio: Maintain a particular aspect ratio (for a responsive site)

We'll still have to offer the traditional iframe option for sites like Tumblr, but this JS approach would become the recommended embed.
Output Overlay & Documentation

We'll need to redesign the output overlay to explain more about what's happening with this new approach.  Additionally, we'll need to document the full API, so that more technical clients that take advantage of additional customization.