OBIP-0003: Channels

[drwasho]

OBIP-0003: Channels

Proposal: https://github.com/OpenBazaar/obips/blob/master/obip-0003.mediawiki
Author: @cpacia

  OBIP: 3
  Title: Channels
  Author: Chris Pacia 
  Discussions-To: #openbazaar-2_0 on Slack, Github Issues, or 
  Status: Draft
  Type: Standards Track
  Created: 2017-9-27
  License: Public Domain

Abstract

Channels are a feature designed to improve the browsing experience in OpenBazaar. Being a decentralized application OpenBazaar faces challenges displaying interesting, relevant, and timely content to users. Most e-commerce platforms solve this problem by using their access to their centralized listing database to curate content for their home page or category landing pages. Since most OpenBazaar implementations are oriented towards consumers and run on either home computers on or mobile devices, it's not feasible for the software to index all listings.

One strategy for dealing with this limitation is to have the application download content from a centralized curator. While this approach would mostly work, it goes strongly against OpenBazaar's core value of decentralization.

The alternative presented here is to open the curation to everyone and allow users to seed their curated content on the OpenBazaar network. By allowing everyone to participate in curation we avoid having a single point of failure. Further we can take advantage of OpenBazaar's distributed architecture to distribute the content around the network ensuring the data will remain available even if the content creator is offline.

Definitions

A channel is one or more user curated pages of content.

A page is a static JSON document containing one or more views that is interpreted by clients. Pages can contain links to other pages creating a browsing experience similar to that of the web.

A view is the most basic element on a page. It contains the data to be displayed and information about how to display it.

Specification

Channel Schema

The channel schema consists of a JSON object containing some metadata and a list of views (to be rendered in order veriticaly):

{
  "name": "OB1",
  "logo": "zb2rhcQdW4Jb9YmJUASEumQg4xetuc9tob9Hofn24g74c12p7",
  "slug": "index",
  "lastUpdated": ""2017-09-28T03:15:51.785762669Z",
  "searchEndpoint": "https://search.ob1.io/search/listings",
  "onClick": "https://clickdata.ob1.io/channel",
  "onLoad": "https://loaddata.ob1.io/channel",
  "version": 1,
  "views": [
    // views here
  ]
}

Only name, logo, slug and views are required. onClick and onLoad are endpoints which clients are expected to POST to for data collection purposes. The POST body should contain the loaded page URI for onLoad or the URL of the clicked item for onClick.
The current version is 1. Slug must unique for each page and set to index for the main channel page.

Types of Views

ImageView

Self explanatory. Used for banner images, product promotions, etc. Images should be hosted on IPFS and can optionally link to a product or another page. Links may use either ob:// (for listings, user pages, or channel pages) or http:// (for channel pages only).

{
  "type": "IMAGE_VIEW",
  "imageHash": "zb2rhcQdW4Jb9YmJUASEumQg4xetuc9tob9Hofn24g74c12p7",
  "Link": "ob://QmYj1ojj3cRKrmkQR3o8KtPqmTbgsZWsgq5grpUpAbjiYx/channel/another_channel_page",
  "height": 275,
  "width": 580
} 

TextView

Display text on the page.

{
  "type": "TEXT_VIEW",
  "text": "Welcome to my channel!",
  "Link": "ob://QmYj1ojj3cRKrmkQR3o8KtPqmTbgsZWsgq5grpUpAbjiYx/channel/another_channel_page",
  "size": 28,
  "font": "noto sans",
  "color": "#343434",
  "align": "center"
} 

ListingGridView

A 4 by x grid of listing cards. Title should be displayed at the top of the view. Button is optional and it displays at the
bottom of the view and gives the ability to link to another page. The listing data must be included.

{  
   "type":"LISTING_GRID_VIEW",
   "title":"New Listings",
   "button":{  
      "Text":"See More",
      "Link":"ob://QmYj1ojj3cRKrmkQR3o8KtPqmTbgsZWsgq5grpUpAbjiYx/channel/another_channel_page"
   },
   "listings":[  
      {  
         "vendor":{  
            "id":"QmWBSdbs7LLR7BdFgtKQA7CUq8aCzoTi74V7UwiwvfYpU5",
            "handle":"@yPayne",
            "avatarHashes":{  
               "tiny":"QmTHCaDpznJStWvPUSiKNDd53VVZmPtnrHx5diGP5gskCx",
               "small":"QmfVecQaoy1pZD3wsHHC82kYg24yhVaqBsAzm5aJCabXPQ"
            }
         },
         "data":{  
            "hash":"zb2rhcQdW4Jb9YmJUASEumQg4xetuc9tob9Hofn24g74c12p7",
            "slug":"air-direct-amplifier",
            "title":"Air Direct Amplifier",
            "thumbnail":{  
               "small":"QmfVecQaoy1pZD3wsHHC82kYg24yhVaqBsAzm5aJCabXPQ",
               "medium":"QmS1z4qW1SiDNtLD1Bfno8WEbFUV8qwb5CQxgR6BREyVTJ"
            },
            "price":{  
               "currencyCode":"btc",
               "amount":34
            },
            "nsfw":true
         }
      }
   ]
}

PaginatedListingView

Similar to the ListingGridView but designed to allow a large number of listing cards to be displayed on the page by using pagination. Clients are free to decide how many listings to display per page and whether or not to offer sorting functionality.

{  
   "type":"PAGINATED_LISTING_VIEW",
   "count": 200,
   "listings":[  
      {  
         "vendor":{  
            "id":"QmWBSdbs7LLR7BdFgtKQA7CUq8aCzoTi74V7UwiwvfYpU5",
            "handle":"@yPayne",
            "avatarHashes":{  
               "tiny":"QmTHCaDpznJStWvPUSiKNDd53VVZmPtnrHx5diGP5gskCx",
               "small":"QmfVecQaoy1pZD3wsHHC82kYg24yhVaqBsAzm5aJCabXPQ"
            }
         },
         "data":{  
            "hash":"zb2rhcQdW4Jb9YmJUASEumQg4xetuc9tob9Hofn24g74c12p7",
            "slug":"air-direct-amplifier",
            "title":"Air Direct Amplifier",
            "thumbnail":{  
               "small":"QmfVecQaoy1pZD3wsHHC82kYg24yhVaqBsAzm5aJCabXPQ",
               "medium":"QmS1z4qW1SiDNtLD1Bfno8WEbFUV8qwb5CQxgR6BREyVTJ"
            },
            "price":{  
               "currencyCode":"btc",
               "amount":34
            },
            "nsfw":true
         }
      }
   ]
}

UserGridView

A 4 by x grid of user cards. Title should be displayed at the top of the view. Button is optional and it displays at the
bottom of the view and gives the ability to link to another page. The user profile data must be included.

{  
   "type":"USER_GRID_VIEW",
   "title":"Top vendors",
   "button":{  
      "Text":"See More",
      "Link":"ob://QmYj1ojj3cRKrmkQR3o8KtPqmTbgsZWsgq5grpUpAbjiYx/channel/another_channel_page"
   },
   "users":[  
      {  
          "id":"QmWBSdbs7LLR7BdFgtKQA7CUq8aCzoTi74V7UwiwvfYpU5",
          "handle":"yPayne.id",
          "avatarHashes":{  
             "tiny":"QmTHCaDpznJStWvPUSiKNDd53VVZmPtnrHx5diGP5gskCx",
             "small":"QmfVecQaoy1pZD3wsHHC82kYg24yhVaqBsAzm5aJCabXPQ"
          },
          "headerHashes":{  
             "tiny":"QmTHCaDpznJStWvPUSiKNDd53VVZmPtnrHx5diGP5gskCx",
             "small":"QmfVecQaoy1pZD3wsHHC82kYg24yhVaqBsAzm5aJCabXPQ"
          },
          "shortDescription": "Webstore specialized in selling unique, interesting and high-quality..."  
      }
   ]
}

PaginatedUserView

The user card equivilent of PaginatedListingView.

{  
   "type":"PAGINATED_USER_VIEW",
   "count": 200,
   "users":[  
      {  
          "id":"QmWBSdbs7LLR7BdFgtKQA7CUq8aCzoTi74V7UwiwvfYpU5",
          "handle":"yPayne.id",
          "avatarHashes":{  
             "tiny":"QmTHCaDpznJStWvPUSiKNDd53VVZmPtnrHx5diGP5gskCx",
             "small":"QmfVecQaoy1pZD3wsHHC82kYg24yhVaqBsAzm5aJCabXPQ"
          },
          "headerHashes":{  
             "tiny":"QmTHCaDpznJStWvPUSiKNDd53VVZmPtnrHx5diGP5gskCx",
             "small":"QmfVecQaoy1pZD3wsHHC82kYg24yhVaqBsAzm5aJCabXPQ"
          },
          "shortDescription": "Webstore specialized in selling unique, interesting and high-quality..."  
      }
   ]
}

SlideshowView

A view which which rotates through the provided image views.

{
  "type": "SLIDESHOW_VIEW",
  "height": 250,
  "width": 400,
  "images": [
    {
      "imageHash": "zb2rhcQdW4Jb9YmJUASEumQg4xetuc9tob9Hofn24g74c12p7",
      "Link": "ob://QmYj1ojj3cRKrmkQR3o8KtPqmTbgsZWsgq5grpUpAbjiYx/channel/another_channel_page"
    }
  ]
} 

CategoryView

A list of categories for the client to render. The optional field breadcrumbs is used to display the current nesting.

{
  "type": "CATEGORY_VIEW",
  "categories": [
    {
      "name": "Marvel",
      "Link": "ob://QmYj1ojj3cRKrmkQR3o8KtPqmTbgsZWsgq5grpUpAbjiYx/channel/marvel"
    },
    {
      "name": "Spiderman",
      "Link": "ob://QmYj1ojj3cRKrmkQR3o8KtPqmTbgsZWsgq5grpUpAbjiYx/channel/spiderman"
    },
    {
      "name": "Superman",
      "Link": "ob://QmYj1ojj3cRKrmkQR3o8KtPqmTbgsZWsgq5grpUpAbjiYx/channel/superman"
    }
  ],
  "breadcrumbs": [
    {
      "name": "Books",
      "Link": "ob://QmYj1ojj3cRKrmkQR3o8KtPqmTbgsZWsgq5grpUpAbjiYx/channel/books"
    },
    {
      "name": "Comic Books",
      "Link": "ob://QmYj1ojj3cRKrmkQR3o8KtPqmTbgsZWsgq5grpUpAbjiYx/channel/comic_books"
    }
  ]
} 

HBox

An HBox allows ImageViews to be aligned horizontally next to each other. HBoxes can be nested inside other HBoxes or inside VBoxes. Only ImageViews, TextViews, HBoxes, and VBoxes are currently supported inside HBoxes. All other types should be ignored.

{
  "type": "HBOX",
  "padding": 10,
  "views": [
  	{
	  "type": "IMAGE_VIEW",
	  "imageHash": "zb2rhcQdW4Jb9YmJUASEumQg4xetuc9tob9Hofn24g74c12p7",
	  "Link": "ob://QmYj1ojj3cRKrmkQR3o8KtPqmTbgsZWsgq5grpUpAbjiYx/channel/another_channel_page",
	  "height": 275,
	  "width": 580
	},
	{
	  "type": "IMAGE_VIEW",
	  "imageHash": "zb2rhcQdW4Jb9YmJUASEumQg4xetuc9tob9Hofn24g74c12p7",
	  "Link": "ob://QmYj1ojj3cRKrmkQR3o8KtPqmTbgsZWsgq5grpUpAbjiYx/channel/another_channel_page",
	  "height": 275,
	  "width": 580
	} 
  ]
} 

VBox

A VBox allows ImageViews to be aligned vertically on top of each other. VBoxes can be nested inside other VBoxes or inside HBoxes. Only ImageViews, TextViews, HBoxes, and VBoxes are currently supported inside VBoxes. All other types should be ignored.

{
  "type": "VBOX",
  "padding": 10,
  "views": [
  	{
	  "type": "IMAGE_VIEW",
	  "imageHash": "zb2rhcQdW4Jb9YmJUASEumQg4xetuc9tob9Hofn24g74c12p7",
	  "Link": "ob://QmYj1ojj3cRKrmkQR3o8KtPqmTbgsZWsgq5grpUpAbjiYx/channel/another_channel_page",
	  "height": 275,
	  "width": 580
	},
	{
	  "type": "IMAGE_VIEW",
	  "imageHash": "zb2rhcQdW4Jb9YmJUASEumQg4xetuc9tob9Hofn24g74c12p7",
	  "Link": "ob://QmYj1ojj3cRKrmkQR3o8KtPqmTbgsZWsgq5grpUpAbjiYx/channel/another_channel_page",
	  "height": 275,
	  "width": 580
	} 
  ]
} 

Loading a channel

When entering and saving a new channel a user should be able to enter either an OB URI (ob://ob1.io/channel) or HTTP URL (https://ob1.io/channel).
Clients should be able to fetch the main page json from either source.

Extensibility

Clients should ignore view types they do not know how to parse. This allows us to introduce new views without breaking old clients.

FAQ

Will the channel be slow to load and provide a bad experience?

This OBIP calls for listing data and user data to be provided in each view which means the only loading that needs to be done is the initial JSON document and images. It would be great to make it so these views do not need to provide the data and instead it could be fetched from IPNS but current IPNS speeds are too slow for this to be feasible. As IPNS optimizations come to fruition this option can be revisted.

As for initial page load, pages served over IPNS will be subject to IPNS load times but serving pages via HTTP is an option for those that care about page load speed and have the resources and technical knowledge to do so. Serving pages via HTTP also allows for dynamic page creation.

Given that the data must be provided with each view, wont the channel data get stale?

For pages served via HTTP the server can build the page using the most up to date data it knows about.

For pages served via IPNS, the responsibility falls on the channel creator to update and republish their channel periodically. Implementions can fairly easily provide automated functionality to iterate over the channel data, update each listing/user with current data, and republish. How stale a channel is will be dependent on the tools one use to curate the channel and how committed they are to maintaining it.

Wont users see a bunch of unmaintained channels with stale data?

Channels served via IPNS will drop out of the network after a week if the creator does not republish his data. It's unlikely stale channels will persist. Additionally this OBIP does not specify channel discovery which could itself be curated by a channel and only list well maintained channels.

How does a user actually curate a channel? Do they need a crawler? What tool do they use? Or is it entirely a manual process?

Curation is not specified by this OBIP as it will depend on the tools available to the user. API calls to create, update, and publish a channel are pretty easy to create and fairly easy to use. Crawlers are not needed per se as curators can find listings via other channels or via search. Though specialized crawlers might be desireable for curating listings behind Tor, as an example. Open source crawlers that do this already exist.

Less technical users will probably need to wait until UIs are created which make building channels more user friendly. Even without such UIs simply creating a JSON text file is orders of magnitude easier to do than building a search engine and a step in the right direction.

Is the average person going to do this? What is their incentive to do so?

Average people creating and sharing channels would certainly improve user engagment and interaction with the app but isn't necessary for the purpose of improving the browsing experience. The user experience would still be much improved if only several big players create and maintain channels provided that there is free entry and competition.

Further, there may be a financial incentive to create a channel. It's pretty trivial right now to create a "Buy ad space on my channel" listing which may provide a revenue stream large enough to compensate for the time invested into maintaining the channel.

Isn't there going to be all kinds of cross platform issues when rending the channel?

The channel schema provides the data to be displayed and a rough suggestion about how that data should be used. It's up to each client implementation to decide how best to render the data. For example, the ListingGridView might work well as a 4x2 grid on desktop, but mobile designers may choose to render it as an ImageSwitcher with swipe gestures. Futher platform specific channels can also be created, ex) ob://ob1.io/channel/mobile.

Doesn't this design preclude things pagination and/or sorting by price/rating, etc?

No. The PaginatedListingView and PaginatedUserView can probably hold several thousand listing/user data objects while still keeping the page to a reasonable size. Clients can paginate the listings/user cards and offer sorting as they desire. Should a page require more than one thousand listings, say, it would probably make sense, both from a UX and efficiency perspective, to break that view up into separate pages. For example, if you are trying to build a page that contains comic book listings and you have more than one thousand comic books, you should probably break the page up into multiple pages of comic book subcategories.

[drwasho]

@rmisio

This OBIP calls for listing data and user data to be provided in each view which means the only loading that needs to be done is the initial JSON document and images. It would be great to make it so these views do not need to provide the data and instead it could be fetched from IPNS but current IPNS speeds are too slow for this to be feasible. As IPNS optimizations come to fruition this option can be revisted.

Hmmm... giving the user free reign to construct whatever data they want seems really risky.

For example, a channel author can give us a listing with the title ugly dog face and then link to a legitmate listing where a model is advertising photos of herself.

Another example is a channel author could represent a listing with a price of 100 as 10. When you click the listing with the intent to buy, you may gloss over the price and not compute the 100 because the 10 you saw earlier is in your mind.

Allowing the channel author complete control of how they represent listings while linking to real listings seem fraught with opportuntites for malisciousness.

Not sure how we would minimize or prevent this?

[drwasho]

@rmisio

onClick and onLoad are endpoints which clients are expected to POST to for data collection purposes. The POST body should contain the loaded page URI for onLoad or the URL of the clicked item for onClick.

Unless I'm misunderstanding this, wouldn't we need user approval before tracking their viewing / clicking habits?

[drwasho]

@rmisio

{
  "type": "TEXT_VIEW",
  "text": "Welcome to my channel!",
  "Link": "ob://QmYj1ojj3cRKrmkQR3o8KtPqmTbgsZWsgq5grpUpAbjiYx/channel/another_channel_page",
  "size": 28,
  "font": "noto sans",
  "color": "#343434",
  "align": "center"
} 

@morebrownies Do we want to expose fonts and font size to the channel author. Stuff like this gives them a lot of rope and if they're not careful it could result in a really ugly (or broken) layout. It also results in an inconsistent Channel look and feel across the app.

I suppose if we opened up some exta styling to just a headline, that would be one thing, but in theory the channel author could create 50 text views and put them all over the page.

If we did expose text color to them, we'd also need to let them control the background of the page, otherwise their text color might not play well with the background color from the theme.

[drwasho]

@rmisio

A 4 by x grid of listing cards.
I'm not sure I would document this as 4 by X. I think the amount per row should probably be driven by the client since each client has such unique space constraints.

I think it's fine to leave it generic that the LISTING_GRID_VIEW will display listings in a grid, which may be 10 X x on wide screens or 1 by X on mobile.

[drwasho]

@rmisio

The user card equivilent of PaginatedListingView.

hmmm... I don't have the designs in front of me so I don't have the full context, but a few thoughts:

First, do we want to expose paginating to the channel author? Since this is pagination that is expected to be done on the client, would it not be better for the author to just provide as many listings as they feel comfortable and leave it up to individual clients to decide whether they want to paginate or not.

I would think if a channel creator gave a list of 500 user cards, a client would want to paginate that regardless of whether the channel author indicated they wanted that.

It's just another one of those where I question if we're giving the author too much rope.

If we do decide to allow pagination to be controlled by the Channel author, my second thought is, do we need separate non-paginated and paginate-listing types? It seems like the data is so similar that it could be collapsed into one, with pagination applied if some specific properties are present.

[drwasho]

@rmisio

Can you give an example Page schema? What would it's relationship be to a Channel schema (instead of Views in the channel, it would have a page or pages...?)?

[drwasho]

@cpacia

Unless I'm misunderstanding this, wouldn't we need user approval before tracking their viewing / clicking habits?

We could definitely ask... though I would expect that would pretty dramatically reduce the participation rate. But if we could get a accurate data on what % of users allow data collection then maybe we could extrapolate for the rest of the users.

[drwasho]

@cpacia

I'm not sure I would document this as 4 by X. I think the amount per row should probably be driven by the client since each client has such unique space constraints.

Yeah x was a bit of a placeholder for discussion. In wolf's designs it's 4x2 which seems fine to me. Also 8 lisitngs would probably be a good amount to swipe around with on mobile.

[drwasho]

@cpacia

hmmm... I don't have the designs in front of me so I don't have the full context, but a few thoughts:

So let me give my thinking here. Most of the other views are really geared towards creating landing pages with a mix of different views to make them look unique.

But if you're trying to categorize a bunch of listings at some point you just want a page with a bunch of listings that renders very similar to what we have in search. That's the primary purpose of that paginated view. It wouldn't really be used on index page, but maybe if someone clicked on a "comic books" category then we would use it for that. Just a full page of listings with some arrows at the bottom for changing pages.

I'm thinking this one would differ from the ListingGridView in that this one allows for many listings to be rendered whereas the ListingGridView is just maybe a 4x2 widget with a "see more" button. So for example, we might use the ListingGridView on the home page with the title "New Listings" and when they click "See more" then it takes them to a new page with a single PaginatedListingView that show all new listings (or at least a reasonable amount of them).

[drwasho]

@cpacia

Can you give an example Page schema? What would it's relationship be to a Channel schema (instead of Views in the channel, it would have a page or pages...?)?

I'm probably unclear. I'm proposing every page use the schema defined under the Channel shema (maybe that section could be called Page schema instead). So the client only has one job... take the json and render it. Each page uses the same schema (including the index page), they just might have a different collection of views. The links found in the image or category views would trigger the client to load and render a new page when clicked on.

[drwasho]

@rmisio

Yeah x was a bit of a placeholder for discussion. In wolf's designs it's 4x2 which seems fine to me. Also 8 lisitngs would probably be a good amount to swipe around with on mobile.

I meant, I wouldn't even publicize the first number (4 by) because I'd leave it up to the client to decide how to layout the grid, which might be 10 in a row for large desktops or 1 per row for mobile.

[drwasho]

@rmisio

I'm thinking this one would differ from the ListingGridView in that this one allows for many listings to be rendered whereas the ListingGridView is just maybe a 4x2 widget with a "see more" button.

My thinking is that it shouldn't be a decision of the channel author of whether a grid of listings is or is not paginated or how many listing to show per page.

I think this should be a decision of the client since different clients have different screen constraints as well as being tailored to different bandwidths and hardware.

So, the Channel author just provides the "listing grid view" listing type and then provides a list of listings (which may be 4 with a link to see more -or- may be a list of 500 (which also could include a link to see more if they want)).

The client based on their specific situation would decide how it wants to represent that grid. A mobile device (phone) might put them all in one column and paginate after 8 (if there are that many) whereas a wide desktop may put them in rows of 8 and paginate after 32.

@morebrownies what do you think? (you may want to read my initial comment and Chris's response for full context)

[drwasho]

@cpacia

@rmisio that's probably works. My thinking was the GridView would be a combination of a title, listings, and button. But that was before adding a text view. I suppose they could just use a generic ListingView to recreate the same thing and just slap a textview above it.

[drwasho]

@morebrownies

{
  "type": "TEXT_VIEW",
  "text": "Welcome to my channel!",
  "Link": "ob://QmYj1ojj3cRKrmkQR3o8KtPqmTbgsZWsgq5grpUpAbjiYx/channel/another_channel_page",
  "size": 28,
  "font": "noto sans",
  "color": "#343434",
  "align": "center"
} 

@morebrownies Do we want to expose fonts and font size to the channel author. Stuff like this gives them a lot of rope and if they're not careful it could result in a really ugly (or broken) layout. It also results in an inconsistent Channel look and feel across the app.

My initial thought is we should keep most styling params (fonts, sizes, alignment) outside of the data structure and defer to the clients to choose how to display the data. Clients may be anything from: websites, desktop apps, mobile apps, smart watches, VR, and future devices we're unaware of at the current time. It's going to be next to impossible to carry over the preferred styling across platforms.

The font parameter can especially be problematic as it may introduce licensing issues. For example, a font license on a website vs a mobile app typically comes with a different price tag.

I imagine most clients will ignore styling params provided in the data structure and instead present their own custom UI.