Quickstart

Adding whiteboard to your site is quick and easy. To get the basic version with no advanced features you are not required to register, just add this code to your HTML document:

<body>
    <div style="width: 600px; height: 400px;" id="aww-wrapper">
    <!-- Element in which the whiteboard will be shown
              – modify style as needed -->
    </div>
    <script src="https://awwapp.com/static/widget/js/aww3.min.js">
    </script>
    <script type="text/javascript">
        var aww = new AwwBoard('#aww-wrapper', {
        });
    </script>
</body>

IMPORTANT: Do not download AWW scripts to your site and host them yourself, as this will break the sharing functionality. Use the files directly from AWW servers, as is shown in the examples here.

If you wish to have more options to modify whiteboard to your needs, register and subscribe to one of our plans so you can get your API key which enables your plan features.

To integrate whiteboard you need to first add your domain in account information of the website in which you wish to use whiteboard (API key is only valid for the domain you submit here). If you have a test version of your website on a different domain (or more than one), you can add them all there.

You can find your API key and API secret in your account page under API Keys subpage (example: '391e33ce-16fb-41e9-aced-ad424988deba' ). And then add your API key in to the code:

<script type="text/javascript">
        var aww = new AwwBoard('#aww-wrapper', {
            /* make sure you're using your own key here */
            apiKey: '391e33ce-16fb-41e9-aced-ad424988deba'
        });
</script>

To use the advanced feature of sharing the board you will need Board ID which will allow you to always connect to the same shared board. Board ID is a unique text for the board on that page and any widget using it can connect to the same board:

<script type="text/javascript">
        var aww = new AwwBoard('#aww-wrapper', {
            /* make sure you're using your own key here */
            apiKey: '391e33ce-16fb-41e9-aced-ad424988deba',
            /* put a unique text here */
            boardLink: 'Your-Board-ID'
        });
</script>

API Docs Overview

When setting your whiteboard widget in code, you have several options at your disposal all of which are described in detail below.

AWW consists of three components:

  • whiteboard widget that runs inside the page
  • realtime sharing service that provides the whiteboard sharing functionality, hosted on AWW servers
  • image post and download service hosted on AWW servers

AwwApp has a concept of shared boards, where each board is separate, and identified by an unique string ID. By default, URL query strings are used to identify board IDs. For example, board TEST-BOARD would have URL: http://example.com/yourpage?awwBoard=TEST-BOARD

IMPORTANT: Do not download AWW scripts to your site and host them yourself, as this will break the sharing functionality. Use the files directly from AWW servers, as is shown in the examples here.

To create a whiteboard, invoke a AwwBoard() method in which you write the selected element in which you want to add the whiteboard and preferred options.

new AwwBoard(element, {options})

  • element [string | object] – contains a reference to the element in which whiteboard is
  • {options} [object] – options object
<div id="aww-wrapper"></div>
<script src="https://awwapp.com/static/widget/js/aww.min.js">
</script>
<script type="text/javascript">
      var aww = new AwwBoard('#aww-wrapper', {
            apiKey: '391e33ce-16fb-41e9-aced-ad424988deba',
            autoJoin: true,
            boardLink: '5aj5342-56tz-uhjk-9874',
            sizes: [3, 5, 8, 13, 20],
            fontSizes: [10, 12, 16, 22, 30],
            menuOrder: ['colors', 'sizes', 'tools', 'admin',
              'utils'],
            tools: ['pencil', 'eraser', 'text', 'image'],
            colors: [ "#000000", "#f44336", "#4caf50", "#2196f3",
              "#ffc107", "#9c27b0",     "#e91e63", "#795548"],
            defaultColor: "#000000",
            defaultSize: 8,
            defaultTool: 'pencil',
     });
</script>

AwwBoard options

apiKey [string]

The purpose of apiKey is to enable your premium plan features like voice chat and whiteboard sharing. You can find your apiKey in account information. Here's an example:

apiKey: '391e33ce-16fb-41e9-aced-ad424988deba'

autoJoin [boolean]

With the default value as true, whiteboard widget will automatically connect to the shared board if its ID is set in the URL as a query string or if you set your own boardLink in the options. If autoJoin is set to false, the whiteboard widget will not connect to the shared board even if an ID is present in the URL or you set a boardLink.

autoJoin: false

When set, the whiteboard widget will use its value as the board link ID to connect to instead of the URL query string. If autoJoin is set to true, then it will automatically create or join the specified board. By default this option is not set and if you are setting it, it should be a unique, unguessable string of text.

boardLink: '5aj5342-56tz-uhjk-9874'

defaultColor [string]

With this option you can set a default color that will appear as the color button on the main menu. It doesn't have to be a part of your color sub-menu array. As with above mentioned colors, you can set in all standard CSS codes. The default of this option is black. Here is an example:

defaultColor: "#000000"

defaultSize [number]

With this option you can set a default size, a size you start with when you begin painting a new picture. Default of this option is 8. Here is an example:

defaultSize: 8

defaultTool [string]

With this option you can set a default tool which you use to paint a picture with, the options are the same as in above mentioned tools: pencil, eraser, text, image. Default of this option is pencil. Here is an example:

defaultTool: 'pencil'

multiPage [boolean]

With this option you can enable your board to have multiple pages. By default, this flag is set to false when the board will have only one page and by setting it to true, you will see a navigation bar on the bottom of the board. Keep in mind that navigation bar, along with the plus sign for adding another page is visible only after the first thing is drawn on the current page. Pages on the board are unlimited.

multiPage: true

sendUserPointer [boolean]

Enable the board to send user pointers to other users on the board. This option only enables pointers of the current user to be sent so others can see it.

sendUserPointer: true

showUserPointers [boolean]

Show other users' pointers on the current board. In order for this to work other users' boards need to have sendUserPointer flag set to true.

showUserPointers: true

connectAllAsReadOnly [boolean]

This flag connects all users as read only on the initialisation of the board (obviously :)). Read only users won't be able to interact with the board but only view it.

connectAllAsReadOnly: true

defaultZoomLevel [number]

Default zoom level is the zoom level which will be set on board initialisation. If you don't set this, board will automatically adjust the zoom level so that all content fits in the screen.

defaultZoomLevel: 5

zoomLevelLimits [array]

Zoom level limits are the limits in which user will be able to zoom in and out. Recommended zoom levels are between [0.5, 2500]. In this range zooming will show accurate board content across all devices and resolutions.

zoomLevelLimits: [0, 2500]

enableZoom [boolean]

Flag to disable or enable zooming in and out of the board.

enableZoom: true

enablePan [boolean]

Flag to disable or enable panning acroos the board.

enablePan: true

AwwBoard methods

Available methods for awwapp are:

Get methods:

awwapp.getZoomLevelLimits()

  • get currently zoom level limits.
  • returns: [array] with 2 numbers (low and high limit)

awwapp.getStrokeColor()

  • get currently stroke color.
  • returns: [string] HEX code of the stroke color

awwapp.getTextColor()

  • get currently stroke color.
  • returns: [string] HEX code of the stroke color

awwapp.getCurrentPage()

  • get currently page on the board.
  • returns: [number] page number starting where 0 is a first page

awwapp.getLastPage()

  • get last page on the board that has any content.
  • returns: [number] page number starting where 0 is a first page

awwapp.getTool()

  • get currently selected tool.
  • returns: [string] name of the currently selected tool

awwapp.getZoomLevel(callback)

  • get currently stroke color.
  • parameter: type [function]
  • returns: [number] current zoom level on the page

awwapp.getPan(callback)

  • get the top left coordinates of the current view in users board.
  • parameter: type [function]
  • returns: [array] x and y coordinates of the top left point in users board view

awwapp.getViewportImage()

  • get currently shown image on the canvas
  • returns: [string] canvas image of the users current view as data URL

awwapp.getMaxViewportImage()

  • get image of with all objects in it
  • returns: [string] canvas image of the entire page view as data URL

awwapp.getPDF()

  • get the PDF document with all board pages exported as pages in the document
  • parameter: type [function]
  • returns: [string] link to the PDF document

awwapp.getBoardInfo()

  • get board information
  • gives information of a shared board (only if the board is shared)
  • returns: [object] has boardLink, boardGuestLink and boardID

awwapp.getBoardUsers()

  • get a list of users on the board
  • parameter: type [function]
  • returns: [object] list of users where key is a uid and value is an object with user data

awwapp.getCurrentUser()

  • get current user.
  • parameter: type [function]
  • returns: [object] current user

awwapp.getOps()

  • get a list of operations
  • gives a list of drawing operations which have been made on canvas from all users
  • returns: [array] list of operations

Set methods:

awwapp.setTool(tool)

  • Changes the current tool
  • parameters:
    • tool [string] - New tool to be used
    • pencil
    • marker
    • lineStraight
    • eraser
    • eraserArea
    • rectangle
    • rectangleFilled
    • ellipse
    • ellipseFilled
    • text
    • postit

awwapp.setStrokeColor(color)

  • Changes the current stroke color
  • parameters:
    • color [string] - '#' followed by the 6 digit HEX code of a color to be selected

awwapp.setTextColor(color)

  • Changes the current text color
  • parameters:
    • color [string] - '#' followed by the 6 digit HEX code of a color to be selected

awwapp.setPage(page)

  • Navigates board to a specific page
  • Will navigate to the last page + 1 if the page number is greater than the number of pages
  • Pages start with page number = 0
  • parameters:
    • page [int] - Page number to go to

awwapp.setZoomLevel(zoomLevel)

  • Changes the zoom level of the board
  • parameters:
    • zoomLevel [number] - zoom level to set the board to

awwapp.setPan(x, y)

  • Changes the top left point of the visible canvas
  • parameters:
    • x [number] - x coordinate for the top left point of the board
    • y [number] - y coordinate for the top left point of the board

awwapp.setUserPermissions(uid, permissionCode)

  • Sets permission for user to allow or disallow him to edit the board
  • permissionCode - 'RW', 'RO'
  • parameters:
    • uid [string] - uid of a user for whom you want to change the permission
    • permissionCode [string] - code for a desired user permission ('RW' - Read-write, 'RO' - Read-only)

    awwapp.setDefaultUserPermission(permissionCode, cb)

    • Sets a permission for all users. Ones that are currently on the board and new ones that come.
    • Requires the board to be connected to the api
    • parameters:
      • permissionCode [string] - code for a desired default user permission
      • cb [function(statusCode, error)] - callback

    awwapp.setZoomLevelLimits(min, max)

    • Sets zoom level limits that restrict the zooming in and out of the board
    • We recommend not setting the limits lower than 0.5 and higher than 2500 because the board might misbehave in some browsers
    • parameters:
      • min [number] - minimum zoom level limit
      • max [number] - maximum zoom level limit

    awwapp.setUserName(name)

    • Sets a human readable name for user
    • This is needed if showing user pointers
    • parameters:
      • name [string] - name for the user

    awwapp.setShowUserPointers(enable)

    • Enable or disable other users pointers to show
    • If using pointers it is recommended to set names for each user
    • parameters
      • enable [boolean] - flag to enable or disable other users pointers to show

    awwapp.setSendUserPointer(enable)

    • Enable or disable sending current user pointer to other users
    • parameters
      • enable [boolean] - flag to enable or disable sending current user pointer

    awwapp.setEnablePan(enable)

    • Enable or disable panning by user
    • parameters
      • enable [boolean] - flag to enable or disable panning

    awwapp.setEnableZoom(enable)

    • Enable or disable zooming by user
    • parameters
      • enable [boolean] - flag to enable or disable zooming

    Do methods:

    awwapp.fitContentToScreen()

    • Repositions zoom level and pan point so that the entire content on the page is visible and positioned to the top left point of the board

    awwapp.zoomIn()

    • Zooms the board in by one step

    awwapp.zoomOut()

    • Zooms the board out by one step

    awwapp.clearPage(page)

    • Deletes all ops from the current page
    • parameters:
      • page [number] - page on which we want to delete ops

    awwapp.pushOps(ops)

    • Push ops to the board
    • parameters:
      • ops [array] - ops to draw and push onto the board

    awwapp.joinBoard(link)

    • Join board with optional link
    • parameters
      • link [string] - (optional) desired boardLink, if the link is not set, a new board will be created

    awwapp.leaveBoard()

    • Disconnect from board

    awwapp.sendChatMessage(message, userUid)

    • Sends a chat message
    • parameters
      • message [function] - message to be sent
      • userUid [string]- uid of a user from which a message will be sent

    awwapp.doUndo()

    • does undo of the previous own operation (not someone else's in case there are multiple users of one shared board)

    awwapp.redrawBoard()

    • Redraws the canvas to accept previously made changes like setting the zoom level

    Callback methods:

    awwapp.onChatMessage(cb)

    • Is called when a chat message is being broadcasted by another user
    • parameters
      • cb {function} - callback that is called when someone sends a message
      • returns {string, string, string} - chat message, user uid and time when the message was sent

    awwapp.onPageChange(cb)

    • Is called when a page on the board is changed
    • parameters
      • cb {function} - callback that is called when a page is changed
      • returns {number} - page number of the page that is changing to

    awwapp.onJoinBoard(cb)

    • Is called when any user joins the board
    • parameters
      • cb {function} - callback that is called when someone leaves the board
      • returns {object} - user object of a user that joined the board

    awwapp.onLeaveBoard(cb)

    • Is called when any user leaves the board
    • parameters
      • cb {function} - callback that is called when someone leaves the board
      • returns {object} - user object of a user that left the board

    Draw methods:

    awwapp.uploadImageFromComputer(cb, cb2, disableCanvasUpload)

    • Open image selection dialog
    • Has to be used in callback of user initiated event
    • parameters:
      • cb {function} - callback that is called when a user picks an image
      • cb2 {function} - callback that is called when a user edits an image on canvas (is called only if disableEditing not set to true)
      • disableCanvasUpload {boolean} - if set to true, the image won't be drawn on the board
      • returns cb {string} - base64 encoded image that user selected
      • returns cb2 {object} - returns an image object with base64 encoded image and position/rotation parameters

    awwapp.uploadImageFromUrl(src, cb)

    • Opens image editor with specified image URL
    • parameters:
      • src {string} - URL of the image to put onto canvas (can be data URL)
      • cb {function} - callback that is called when a user edits an image on canvas
      • returns cb {object} - returns an image object with base64 encoded image and position/rotation parameters

    awwapp.uploadPresentationFromComputer(cb, cb2, disableCanvasUpload)

    • Open presentation selection dialog
    • has to be used in callback of user initiated event
    • can be used for uploading PDF, PPT and PPTX files
    • Presentation is uploaded on the top left point of the current viewport of the user with screen height and fixed aspect ratio
    • parameters:
      • cb {function} - callback that is called when a user picks an image
      • cb2 {function} - called when the presentation is ready to be drawn on canvas (is called only if disableEditing not set to true)
      • disableCanvasUpload {boolean} - if set to true, the presentation won't be drawn on the board
      • returns cb {string} - url with the presentation in PDF format
      • returns cb2 {array} - an array of presentation pages as image objects with image URL and position/rotation parameters

    awwapp.uploadPresentationFromUrl(src, cb)

    • Loads PDF or PPT presentation with specified image URL
    • parameters:
      • src {string} - URL of the presentation to put onto canvas (can be data URL)
      • cb {function} - called when the presentation is ready to be drawn on canvas
      • returns cb {array} - an array of presentation pages as image objects with image URL and position/rotation parameters

    awwapp.eraseArea(points, page)

    • Erases an area
    • parameters:
      • points {Array} - array of points in area - one point is array of two numbers [x, y]
      • page {number} - page on which the op will take place

    awwapp.drawLine(color, width, points, page)

    • Draws shape defined as array of points
    • parameters:
      • color {string} - '#' followed by the 6 digit HEX code or a rgba object with defined alpha of the stroke color
      • width {number} - width of the stroke in pixels relative to the canvas with zoom level 1
      • points {array} - list of drawing points - one point is array of two numbers [x, y]
      • page {number} - page on which the op will take place

    awwapp.erase(color, width, points, page)

    • Erases everything under a stroke defined by an array of points - basically a regular eraser
    • parameters:
      • color {string} - '#' followed by the 6 digit HEX code or a rgba object with defined alpha of the stroke color
      • width {number} - width of the stroke in pixels relative to the canvas with zoom level 1
      • points {array} - list of drawing points - one point is array of two numbers [x, y]
      • page {number} - page on which the op will take place

    awwapp.drawRectangle(color, size, x, y, w, h, filled, page)

    • Draws a rectangle
    • parameters:
      • color {string} - '#' followed by the 6 digit HEX code or a rgba object with defined alpha of the stroke/fill color
      • size {number} - width of the stroke in pixels relative to the canvas with zoom level 1 (not applicable when filled === true)
      • x {number} - X coordinate of the top left point of the rectangle
      • y {number} - Y coordinate of the top left point of the rectangle
      • h {number} - height of the rectangle
      • w {number} - width of the rectangle
      • filled {boolean} - if set to true, rectangle will be filled with the color
      • page {number} - page on which the op will take place

    awwapp.drawEllipse(color, size, x, y, r, w, h, filled, page)

    • Draws an ellipse
    • will result in circle if w === h
    • parameters:
      • color {string} - '#' followed by the 6 digit HEX code or a rgba object with defined alpha of the stroke/fill color
      • size {number} - width of the stroke in pixels relative to the canvas with zoom level 1 (not applicable when filled === true)
      • x {number} - X coordinate of the middle point of the ellipse
      • y {number} - Y coordinate of the middle point of the ellipse
      • r {number} - radius of the circle
      • w {number} - width of the circle
      • h {number} - height of the circle
      • filled {boolean} - if set to true, ellipse will be filled with the color
      • page {number} - page on which the op will take place

    awwapp.drawStickyNote(text, x, y, w, h, color, fontSize, lineHeight, shadowSize, fontWeight, page)

    • Draws a sticky note
    • parameters:
      • color {string} - '#' followed by the 6 digit HEX code of the sticky note background color
      • text - text to be written on the sticky note
      • h {number} - height of the sticky note
      • w {number} - width of the sticky note
      • x {number} - X coordinate of the top left point of the sticky note
      • y {number} - Y coordinate of the top left point of the sticky note
      • fontSize {number} - size of the font on the sticky note
      • lineHeight {number} - line height of the font on the sticky note
      • shadowSize {number} - shadow size of the sticky note
      • fontWeight {number} - weight of the font on the sticky note
      • page {number} - page on which the op will take place

    awwapp.drawText(text, x, y, w, h, color, fontSize, lineHeight, fontWeight, page)

    • Draws a text
    • parameters:
      • color {string} - '#' followed by the 6 digit HEX code of the text color
      • text - text to be drawn
      • h {number} - height of the text field
      • w {number} - width of the text field
      • x {number} - X coordinate of the top left point of the text field
      • y {number} - Y coordinate of the top left point of the text field
      • fontSize {number} - size of the text font
      • lineHeight {number} - line height of the text font
      • fontWeight {number} - weight of the font on the text field
      • page {number} - page on which the op will take place

    awwapp.drawStraightLine(p1, p2, color, size, page)

    • Draws a straight line defined by two points
    • parameters:
      • p1 {array} - coordinate of the first point - [x, y]
      • p2 {array} - coordinate of the second point - [x, y]
      • color {string} - '#' followed by the 6 digit HEX code or a rgba object with defined alpha of the stroke color
      • size {number} - width of the stroke in pixels relative to the canvas with zoom level 1
      • page {number} - page on which the op will take place

    awwapp.drawImage(url, x, y, w, h, r, page)

    • Draw image to canvas
    • parameters:
      • url {string} - url of the image
      • x {number} - X coordinate of the top left point of the image
      • y {number} - Y coordinate of the top left point of the image
      • w {number} - width of the image
      • h {number} - height of the image
      • r {number} - rotation of the image
      • page {number} - page on which the op will take place

    awwapp.moveOps(opsToMove, point)

    • Moves an object on the board
    • if multiple objects are selected, they will be moved to the point defined where first objects top left point will be alligned with the defined point and rest of objects will have the same relative distance between each other
    • parameters:
      • opsToMove {array} - list of ops objects that you want to move
      • point {array} - point to move objects to

    awwapp.deleteOps(opsToDelete)

    • Deletes objects from the board
    • parameters:
      • opsToDelete {array} - list of objects with key opid and string value from objects you want to delete
      • [{opid: 'some-opid-1'}, {opid: 'some-opid-2'}]