Skip to content

bitmark Resources

A quiz Bit often refers to a text to read, like a news article, an extract from a book or magazine or to a video to watch, an audio file to listen to or an image to describe.

With bitmark, it is possible to attach such a resource to any Bit.

By design, a Bit contains one single, optional resource. This allows us to keep the standard and implementations of the standard in the clients simple but still very powerful ("KISS").

The vast majority of real world learning material, be it in text books, online or in LMS's, only use one single resource anyway. One picture to describe, one audio to listen to, one video to watch, ...

However, some specialized Bits allow for several resources like media files.

If one specific resource is not sufficient for your needs, you can always choose to use bitmark++ as the text format for a Bit or attach a full featured bitmark++ article. An article in bitmark++ text format can contain text and an unlimited number of images and many more advanced features.

Common Properties

A resource contains several standard properties which are shared among all types of resources. In addition, it contains a property with the name of its type (video in the example below) to contain all resource specific information.

    ...
    "resource": {
        "type": "video",
        "preview": ...,
        "search": ...,
        "private": ...,

        "video": {
            ...
        }
    },
    ...

A resource of type video with its video property.

Resource Type

Status: Release Candidate v1

The type of the resource is defined by the type property. A resource contains a property with the name of its type that holds all resource specific information. All other properties are shared among all different types of resources.

Resource types can also be used for filtering at API level. See Full Text Search and Filter

bit                           Data Type, Description
resource.type "image", "image-online", "image-zoom", "audio", "audio-online", "video", "video-online", "article", "article-online", "document, "document-online", "app"

Resource Preview

Status: Release Candidate v1

Resources have an optional preview.

If the preview is available, the clients must show this preview instead of the resource itself.

If there is no explicit preview, a client might still choose to display a preview only of a certain resource. Be it because of the length of a resource (e.g. very long news article) or be it because the client does not support a certain resource natively and needs an external helper application to do so.

All of the preview properties are optional.

    "resource": {
        "preview": {
            "title": "Cat",
            "description": "Cat",
            "icon": null,
            "image": {
                "src1x": "http://cdn.bitmark.cloud/books/com.firstpub.book98789/cat3_64x64.jpg",
                "src2x": "http://cdn.bitmark.cloud/books/com.firstpub.book98789/cat3_64x64@2x.jpg",
                "src3x": null,
                "format": "basic",
                "size": "64x64",
                ...
            }
        }
        ...
    },
resource Data Type, Description
title String, bitmark--, if declared by the bit type (not the resource type!), optional
Please use short titles only.
description String, bitmark--, if declared by the bit type (not the resource type!), optional
A description like a summary or the first few lines of the resource, if appropriate. Long text might be truncated by the clients. Clients typically show max. 2 to 3 lines.
image Image, optional
The preview image is used to show a preview of the resource. Often in combination with the preview title and description.
icon Icon, optional
The preview icon is often used in combination with the preview title and description and as a fallback of a missing preview image.

Resource Icon

Status: Release Candidate v1

The icon property of the resource comes in two flavors. As an svg string or as a Material Design, Octicons or Font Awsome icon.

    ...
    "resource": {
        "preview": {
            "icon": {
                "svg": "<svg aria-hidden=\"true\" focusable=\"false\" data-prefix=\"fas\" data-icon=\"file-word\" class=\"svg-inline--fa fa-file-word fa-w-12\" role=\"img\" xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 384 512\"><path fill=\"currentColor\" d=\"M224 136V0H24C10.7 0 0 10.7 0 24v464c0 13.3 10.7 24 24 24h336c13.3 0 24-10.7 24-24V160H248c-13.2 0-24-10.8-24-24zm57.1 120H305c7.7 0 13.4 7.1 11.7 14.7l-38 168c-1.2 5.5-6.1 9.3-11.7 9.3h-38c-5.5 0-10.3-3.8-11.6-9.1-25.8-103.5-20.8-81.2-25.6-110.5h-.5c-1.1 14.3-2.4 17.4-25.6 110.5-1.3 5.3-6.1 9.1-11.6 9.1H117c-5.6 0-10.5-3.9-11.7-9.4l-37.8-168c-1.7-7.5 4-14.6 11.7-14.6h24.5c5.7 0 10.7 4 11.8 9.7 15.6 78 20.1 109.5 21 122.2 1.6-10.2 7.3-32.7 29.4-122.7 1.3-5.4 6.1-9.1 11.7-9.1h29.1c5.6 0 10.4 3.8 11.7 9.2 24 100.4 28.8 124 29.6 129.4-.2-11.2-2.6-17.8 21.6-129.2 1-5.6 5.9-9.5 11.5-9.5zM384 121.9v6.1H256V0h6.1c6.4 0 12.5 2.5 17 7l97.9 98c4.5 4.5 7 10.6 7 16.9z\"></path></svg>",
                "license": "https://fontawesome.com/license"
            },
            ...
        }
        ...
    },
    ...

    ...
    "resource": {
        "preview": {
            "icon": {
                "code": ":material-file-excel-outline:",
                "tint": "#1da1f2",
                "license": "https://github.com/Templarian/MaterialDesign/blob/master/LICENSE"
            },
            ...
        }
        ...
    },
    ...

Note

Be aware, you need to add the license of the respective library/font.

The following icon sets are supported. You need to add the library id as a prefix to the icon name and surround it :

Icon Library  
Material Design https://materialdesignicons.com/
Prefix: material-
Example: :material-file-excel-outline:
License: https://github.com/Templarian/MaterialDesign/blob/master/LICENSE
Octicons https://primer.style/octicons/
Prefix: octicons-
Example: :octicons-file-media-24:
Tip: Don't forget to add the size of the icon "-24" in the example above
License: https://github.com/primer/octicons/blob/master/LICENSE
FontAwesome https://fontawesome.com/icons
Prefix: fontawesome-
Example: .fontawesome-solid-brain:
Example: .fontawesome-brands-twitter:
Tip: solid and brands icons are free. Add -solid or -brands infront of the icon name.
License: https://fontawesome.com/license
Icon Tint Color

Icons can be tinted by the color in the tint property.

    ...
        "icon": {
            "code": ":fontawesome-brands-twitter:",
            "tint": "#1da1f2",
            "license": "https://fontawesome.com/license"
        }
    ...

Status: Release Candidate v1

For resources to be found, please include some text that describes the image or text that is part of the image.

    "resource": {
        ...
        "search": "Black cat playing with a toy.",
        ...
    },

The information from this field is never shown to the user, so, you don't have to care about its format at all (from full sentences to comma separated keywords). Just add anything that makes sense to describe the picture. The bitmark API itself might add information to this field on request.

Please don't repeat the alt text of images here to be found.

Note

You might want to extract all text information from images and store it in the search field.

Private

    "resource": {
        "type": "image",

        "image": {
            ...
        },

        ...

        "private": {
            "uploadDetails": {
                "displayHeight": 115.60000000000001,
                "displayWidth": 200,
                "filename": "asus7.jpg",
                "height": 287,
                "width": 500,
                "orientation": 1,
                "xRes": 180,
                "yRes": 180
            },
            "printImage" : "http://intranet/images/print/cat3_highres.tiff",
            ...
        }

        }
    },

The private node is used for private meta data for this resource. This property can be freely used by the publisher for any internal use. There are no restrictions (besides being 100% valid JSON, of course).

Resouces

Image

Status: Release Candidate v1

    "resource": {
        "type": "image",

        "image": {
            "src1x":"http://cdn.bitmark.cloud/images/cat3_big_image.jpg",
            "src2x":"http://cdn.bitmark.cloud/images/cat3_big_image@2x.jpg",
            "src3x":"http://cdn.bitmark.cloud/images/cat3_big_image@3x.jpg",
            "showInIndex": true,
            "format": "basic",
            "size": "640x480",
            "alt": "Black cat playing with a toy.",
            "caption": "Cat playing",
            "license": "https://www.istockphoto.com/en/legal/license-agreement",
            "copyright": "© iStockphoto.com"
        },
        "private": {
            "uploadDetails": {
                "displayHeight": 115,
                "displayWidth": 200,
                ...
            }
        }
    },
bitmark                                           Description, Example
[&image::...] Image URL (Resolution @1x)
[&image:...][@src2x:...] Image URL, Resolution @2x
... Same pattern for all resource types.
[&image:jpg:...] Image URL, image format "jpg"
[&image:basic:...] Image URL, image format "basic (default)"
"basic" stands for "gif", "jpg", "png" and "svg"
The type must macht the file extension (or in case of "basic", match one of the basic file extensions). The main application for setting the type of an image, is, if there is no extension in the url. So, usually, this is not used.
Resource tags are block tags and therefore must start at the beginning of a line.
[&image:...][@showInIndex] Image is listed in the image index of the book, default is false
[&image:...][@alt:...] Alternative Text for this image
[&image:...][@alt:Black cat playing with a toy.]
[&image:...][@caption:...] Caption of this image

The size of an image should not be described by bitmark. Size is set to the real size by the API call when creating a Bit from bitmark.

SVG

In case, the svg contains bitmap data, please use the @src1x, @src2x, ... properties to store the url of the corresponding svg. In case the svg contains vector graphics only, please repeat the same url for all properties

For svg images, the aspect ratio must match, in case a certain size is expected from the API.

Note

We highly recommend using svg as your preferred format, if applicable. Due to some short-comings in handling text, we recommend that all text in your svgs are rendered as paths. Please consider adding the text from the original svg to the resource.search field. See above.

Image-Online

Status: Release Candidate v1

    "resource": {
        "type": "image-online",

        "imageOnline": {
            "provider": "dribble.com",
            "url": "https://dribbble.com/shots/5729146-Home-30",
        },
    },
bitmark                        Description, Example
[&image-online::...] Image Viewer/App URL
Resource tags must start at the beginning of a new line.

Zoom-Image

Status: Draft

    "resource": {
        "type": "image-zoom",

        "preview": {
            "image": {
                "src1x":"http://cdn.bitmark.cloud/books/com.firstpub.book98789/cat3_64x64.jpg",
                "src2x":"http://cdn.bitmark.cloud/books/com.firstpub.book98789/cat3_64x64@2x.jpg",
                "src3x":"http://cdn.bitmark.cloud/books/com.firstpub.book98789/cat3_64x64@3x.jpg",
                "format": "jpg",
                "size": "64x48",
            }
        },

        "imageZoom": {
            "src1x":"http://cdn.bitmark.cloud/images/cat3_big_image.jpg",
            "src2x":"http://cdn.bitmark.cloud/images/cat3_big_image@2x.jpg",
            "src3x":"http://cdn.bitmark.cloud/images/cat3_big_image@3x.jpg",
            "format": "basic",
            "size": "640x480",
            "alt": "Black cat playing with a toy.",
            ...
        },
        ...
    },

See Image for details.

The preview image is optional. In case of no preview, the app needs to create one form the main image.

Audio

Status: Release Candidate v1

    "resource": {
        "type": "audio",

        "audio": {
            "format": "mp3",
            "src": "http://cdn.bitmark.cloud/publishers/3/books/26363/sports.mp3",
            "duration": "PT12M31S",
            "autoplay": true
       }
    },
bitmark                              Description, Example
[&audio::...] Audio File URL
[&audio:mp3:...] Audio File URL, Audio Format mp3
Only "mp3" is supported for now. Please let us know, if you need support for other formats. Please be aware, that you can always use audio-online.

Duration in ISO_8601

Autoplay might not be supported (or intenionally disallowed) in certain environments.

Audio-Online

Status: Draft

    "resource": {
        "type": "audio-online",

        "audioOnline": {
            "provider": "soundcloud.com",
            "url": "https://soundcloud.com/kodak-black/zeze-feat-travis-scott-offset-1",
            "duration": "PT12M31S",
            "autoplay": true
        }
    },
bitmark                        Description, Example
[&audio-online::...] Audio Player/App URL
Resource tags must start at the beginning of a new line.

Duration in ISO_8601

Autoplay might not be supported (or intenionally disallowed) in certain environments.

Video

Status: Release Candidate v1

    "resource": {
        "type": "video",

        "video":{
            "format": "mp4",
            "src": "http://cdn.bitmark.cloud/publishers/3/books/26363/news.mp4",
            "size": "640x480",
            "duration": "PT12M31S",
            "mute": true,
            "autoplay": true,
            "allowSubtitles": true,
            "showSubtitles": true,
            "alt": "Today's News",
            "license": "https://www.gnu.org/licenses/gpl-3.0-standalone.html",
            "copyright": "© iStockphoto.com"
        }
    },
Duration in ISO_8601

Autoplay might not be supported (or intenionally disallowed) in certain environments.

Subtitles must be embedded in the video file.

bitmark                              Description, Example
[&video::...] Video File URL
[&video:mp4:...] Video File URL, Video Format mp4
Only "mp4" is supported for now. Please let us know, if you need support for other formats. Please be aware, that you can always use video-online.

Video-Online

Status: Draft

    "resource": {
        "type": "video-online",
        "videoOnline": {
            "provider": "youtube",
            "url": "https://www.youtube.com/watch?v=RecY5iZn6B0",
            "size": "640x480",
            "duration": "PT12M31S",
            "thumbnails": [
                {
                    "src1x": "www.youtube.com/tumb_201809210816.png",
                    "format": "png",
                    "size": "640x480"
                }
            ]
        }
    },
bitmark                        Description, Example
[&video-online::...] Video Player/App URL
Resource tags must start at the beginning of a new line.

Duration in ISO_8601

ImageWithAudio

    "resource": {
        "type": "imageWithAudio",

        "image": {
            "src1x":"http://cdn.bitmark.cloud/images/cat4.jpg",
            "src2x":"http://cdn.bitmark.cloud/images/cat4@2x.jpg",
            "src3x":"http://cdn.bitmark.cloud/images/cat4@3x.jpg",
            "showInIndex": true,
            "format": "basic",
            "size": "640x480",
            "alt": "Hungry black cat."
        },
        "audio": {
            "format": "mp3",
            "src": "http://cdn.bitmark.cloud/publishers/3/books/26363/miau.mp3"
        }
    },
bitmark                              Description, Example
[&imageWithAudio::...] See image resource
[&imageWithAudio:mp3:...] See audio resource

Article

    {
        "type": "match",
        "format": "text",
        "resource": {
            "type": "article",

            "article": {
                "format": "bitmark--",
                "content": "**Nice!**\nFinally I get proper new line support."
            }
        },
        ...
    }

[.match&article:bitmark--]
...
[&article:
**Nice!**
Finally I get proper new line support.
]

Article-Online

    "resource": {
        "type": "article-online",

        "articleOnline": {
            "url" : "https://www.nytimes.com/2018/12/11/opinion/letters/cats.html"
        }
    },
bitmark                        Description, Example
[&article-online::...] bitmark or other Article Reader URL
Mainly just a link to a website.
Resource tags must start at the beginning of a new line.

Website

    "resource": {
        "type": "website",

        "preview": {
            "title": "Apple",
            "description": "Discover the innovative world of Apple and shop everything iPhone, iPad, Apple Watch, Mac, and Apple TV, plus explore accessories, entertainment, and expert device support.",
            "image": {
                "src1x": "https://www.apple.com/ac/structured-data/images/open_graph_logo.png?201809210816",
                "format": "png",
                "size": "1200×630",
            }
        },

        "website": {
            "siteName": "Apple",
            "url":"https://www.apple.com/"
        }
    },
bitmark                        Description, Example
[&website::...] bitmark or other Article Reader URL
Link to a website including preview data.
Resource tags must start at the beginning of a new line.

This resource is heavily inspired by https://ogp.me and often used in .message bits.

Document

    "resource": {
        "type": "document",

        "document": {
            "type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
            "url": "https://cdn.bitbooks.com/animals/cat.docx"
        }
    },
bitmark                                 Description, Example
[&document::...] Document File URL
[&document:application/vnd.openxmlformats-officedocument.wordprocessingml.document:...] Document File URL, Microsoft Word Document (docx)
Format must match file extension.
Format is used to show a suitable icon. Icon must be shown together with the optional preview.

Document-Online

    "resource": {
        "type": "document-online",

        "documentOnline": {
            "provider": "docs.google.com",
            "url": "https://docs.google.com/document/d/5678"
        }
    },
bitmark                        Description, Example
[&document-online::...] Document App URL
Resource tags must start at the beginning of a new line.

App

    "resource": {
        "type": "app",

        "app": {
            "url" : "https://itunes.apple.com/ch/album/like-sugar-single/1392081432?l=en"
        }
    },

    "resource": {
        "type": "app",

        "app": {
            "url" : "tel:+1987987987987"
        }
    },
bitmark                        Description, Example
[&app::...] Deep Link App URL
Please use Universal Links (Apple), Android App Links or custom protocol URLs.
[&app::https://itunes.apple.com/ch/album/like-sugar-single/1392081432?l=en]
[&app::tel:+1987987987987]
Resource tags must start at the beginning of a new line.