Add Bisko to your site

Bisko is a data management platform by GjirafaTech that collects, manages, and provides insights on a vast amount of data from multiple sources. Bisko Web SDK is a JavaScript library and API that allows you to send event data to Bisko. This page describes how to use Bisko Web SDK to configure a site for collecting events.

Setup

To install the SDK, copy the following code and paste it immediately after the <head> tag on every page of your site.

Replace BISKO_ORGANIZATION_CODE with the code of the Bisko organization and BISKO_PROPERTY_ID with the ID of the Bisko property to which you want to send data.

You need only one global snippet per page.

<!-- GjirafaTech Bisko Code -->
<script
  async
  src="https://bisko.gjirafa.net/web/{BISKO_ORGANIZATION_CODE}-sdk.js"
></script>
<script>
  window.biskoQueue = window.biskoQueue || [];
  function bsk() {
    biskoQueue.push(arguments);
  }
  bsk("init", "BISKO_PROPERTY_ID");
  bsk("event", "pageview");
</script>
<!-- End GjirafaTech Bisko Code -->

This snippet loads the Bisko Web SDK, establishes BISKO_PROPERTY_ID as the default Bisko property ID, and sends a pageview event to Bisko.

User identification

By default, Bisko assigns all users a unique ID which is used to track the user across multiple pages and events which are sent. If you want to explicitly identify the user across multiple browsers or devices, you can use your own identifies within Bisko. This is useful if your site has register/login functionallity for users, which means you have your own user IDs for those that are logged it. To use your own ID with Bisko, you can send it as an additional argument in Bisko init method.

Replace BISKO_ORGANIZATION_CODE with the code of the Bisko organization and BISKO_PROPERTY_ID with the ID of the Bisko property to which you want to send data.

Replace USER_ID_HERE with your own user id which you want to send to Bisko.

<!-- GjirafaTech Bisko Code -->
<script
  async
  src="https://bisko.gjirafa.net/web/{BISKO_ORGANIZATION_CODE}-sdk.js"
></script>
<script>
  window.biskoQueue = window.biskoQueue || [];
  function bsk() {
    biskoQueue.push(arguments);
  }
  bsk("init", "BISKO_PROPERTY_ID", "USER_ID_HERE");
  bsk("event", "pageview");
</script>
<!-- End GjirafaTech Bisko Code -->

Additionally you can send extra data which can be used to identify a user within different sites. For example, you can send additional IDs, or other user properties such as gender, age, group etc.

Example code snippet:

<!-- GjirafaTech Bisko Code -->
<script
  async
  src="https://bisko.gjirafa.net/web/{BISKO_ORGANIZATION_CODE}-sdk.js"
></script>
<script>
  window.biskoQueue = window.biskoQueue || [];
  function bsk() {
    biskoQueue.push(arguments);
  }
  bsk("init", "BISKO_PROPERTY_ID", "USER_ID_HERE", {
    gender: "male",
    age: "25",
    group: "A",
  });
  bsk("event", "pageview");
</script>
<!-- End GjirafaTech Bisko Code -->

As seen from the samples above the init() function expects three parameters:

PARAMETER	DATATYPE	REQUIRED	DESCRIPTION
propertyId	INTEGER	TRUE	The identification number of you property created within your organization.
userId	STRING	FALSE	The user identifier within your website.
userProperties	OBJECT	FALSE	Extra user properties that you want to be added to the collected data.

User consent

<!-- GjirafaTech Bisko Code -->
<script async src="./script.js"></script>
<script>
  window.biskoQueue = window.biskoQueue || [];
  function bsk(){biskoQueue.push(arguments);}
  bsk('init', 'BISKO_PROPERTY_ID');

  //This is used specifically for user consent.
  //Organization Alias List is a list of organizations alias.
  bsk('consent', ['ORGANIZATIONS', 'ALIAS', 'LIST'])

  bsk('event', 'pageview')
</script>
<!-- End GjirafaTech Bisko Code -->

Event collection

Standard events are predefined user actions that correspond to common activities, such as reading an article, viewing a product, or watching a video. All standard events are collected by calling the SDK's bsk('event') function, with the event name. These events have predefined parameters that are associated with them, and the data from these events is used to calculate default metrics such as pageviews, searches, impressions, etc. For example, here's an event which collects a page view:

bsk("event", "pageview");

Since the event name is a string, you can send any text that covers your needs:

bsk("event", "pageview");
bsk("event", "search");
bsk("event", "view");
bsk("event", "read");

IMPORTANT
The SDK's init method must already be called on every page where you want to collect events.

Event parameters

Standard events support properties, which allow you to include an object containing additional information about an event, such as ID, name, type, description etc.

The predefined properties that can be collected for the content where the event happened are:

PROPERTY	DATATYPE	DESCRIPTION
Id	STRING	The identifier of the content.
Name	STRING	The name of the content.
Type	STRING	Type of content, i.e. "video", "news article".
Description	STRING	Description of the content.
Category	ARRAY	A string array of the content categories.
ImageUrl	STRING	The url of the main image of the content.
Value	STRING	Value of content, i.e. for ecommerce "100 $".
Keywords	ARRAY	A string array of keywords related to the content.
Author	STRING	The author of the content.
Quantity	INTEGER	Quantity of the content.

All these properties are optional, so not sending any of them does not pose a problem.

In addition to the predefined properties mentioned above, custom properties that seem relevant to the event can be added to the content object.

IMPORTANT
All custom properties must be of type string

General examples

<!-- Pageview without content -->
bsk('event', 'pageview');

<!-- Pageview with content -->
var content = {
    id: '321321312',
    name: 'Content Name',
    type: 'Content Type',
    description: 'Content Description',
    category: [
        'Category',
        'Subcategory 1',
        'Subcategory 2'
    ],
    imageUrl: 'http://content.image/url',
    value: 'Content Value',
    keywords: [
        'Keyword 1',
        'Keyword 2',
        'Keyword 3'
    ],
    author: 'Content Author',
    quantity: 1
};

bsk('event', 'pageview', content);

Article event examples

In this section you can find some example code snippets for saving events related with articles in Bisko

var content = {
  id: "1",
  name: "Apple releases new iPhone version",
  type: "article",
  description:
    "Applce, Inc, has released the newset iPhone version for the users. It contains major changes and new features.",
  category: ["Technology", "Smartphone"],
  imageUrl: "https://magazine.com/apple-iphone-release",
  keywords: ["apple", "iphone", "smartphone"],
  author: "James Smith",
};

bsk("event", "ArticleView", content);

You can use the value property to save the value which is related with the specific event. For example we can use it to save the comment by the user.

var content = {
  id: "1234",
  name: "Samsung releases new Galaxy Note version",
  type: "article",
  description:
    "Samsung has released the newset Galaxy Note version for the users. It contains major changes and new features.",
  value: "Amazing news! The new Galaxy Note looks perfect!", //you can send the content of the comment through this property for example
  category: ["Technology", "Smartphone"],
  imageUrl: "https://magazine.com/samsung-galaxy-note-release",
  keywords: ["samsung", "galaxy note", "note", "smartphone"],
  author: "Nick Smith",
};

bsk("event", "ArticleComment", content);

You can send additional properties as part of the content which can give extra information about the event. For example we can save number of words for the article as part of the article view event. You can name the custom paramters any way that you want and they have to be of type string.

var content = {
  id: "1234",
  name: "Samsung releases new Galaxy Note version",
  type: "article",
  description:
    "Samsung has released the newset Galaxy Note version for the users. It contains major changes and new features.",
  category: ["Technology", "Smartphone"],
  imageUrl: "https://magazine.com/samsung-galaxy-note-release",
  keywords: ["samsung", "galaxy note", "note", "smartphone"],
  author: "Nick Smith",
  nrOfWords: "452", //custom property
};

bsk("event", "ArticleView", content);

Video event examples

In this section you can find some example code snippets for saving events related with videos in Bisko

var content = {
  id: "1",
  name: "SpaceX rocket launch",
  type: "video",
  description: "SpaceX lanunches a new rocket to the orbit.",
  category: ["Science", "Aerospace"],
  imageUrl: "https://magazine.com/spacex-rocket-launch",
  keywords: ["spacex", "orbit", "nasa"],
  author: "William Smith",
};

bsk("event", "VideoView", content);

Sending custom properties as part of the event:

var content = {
  id: "1",
  name: "SpaceX rocket launch",
  type: "video",
  description: "SpaceX lanunches a new rocket to the orbit.",
  category: ["Science", "Aerospace"],
  imageUrl: "https://magazine.com/spacex-rocket-launch",
  keywords: ["spacex", "orbit", "nasa"],
  author: "William Smith",
  length: "1023", //custom property
  serie: "SpaceX Launches", // custom property
};

bsk("event", "VideoView", content);

E-Commerce event examples

In this section you can find some example code snippets for saving events related with e-commerce in Bisko

var content = {
  id: "1",
  name: "Apple iPhone X, 64GB",
  type: "product",
  description: "IPhone X from Apple, 64GB of memory, Black.",
  category: ["Mobile", "Smartphones"],
  imageUrl: "https://image.com/iphone",
  keywords: ["apple", "iphone x", "black"],
  value: "954",
};

bsk("event", "ProductView", content);

If more information is needed to be collected, as shown in previous examples custom properties can be used.

var content = {
  id: "1",
  name: "Apple iPhone X, 64GB",
  type: "product",
  description: "IPhone X from Apple, 64GB of memory, Black.",
  category: ["Mobile", "Smartphones"],
  imageUrl: "https://image.com/iphone",
  keywords: ["apple", "iphone x", "black"],
  quantity: 2,
  value: "1908",
  unitprice: "954", // custom property
  currency: "EUR", // custom property
  brand: "Apple", // custom property
  variant: "Black 64GB", // custom property
  sku: "1299589", // custom property
};

bsk("event", "AddToCart", content);

var content = {
  id: "1",
  name: "Apple iPhone X, 64GB",
  type: "product",
  description: "IPhone X from Apple, 64GB of memory, Black.",
  category: ["Mobile", "Smartphones"],
  imageUrl: "https://image.com/iphone",
  keywords: ["apple", "iphone x", "black"],
  quantity: 2,
  value: "1908",
  unitPrice: "954", // custom property
  currency: "EUR", // custom property
  brand: "Apple", // custom property
  variant: "Black 64GB", // custom property
  sku: "1299589", // custom property
  orderId: "123587", // custom property
};

bsk("event", "Purchase", content);

Events that are not directly related to e-commerce can be collected to:

var content = {
  type: "product",
  category: ["Mobile", "Smartphones"],
  value: "samsung s10",
};

bsk("event", "Search", content);

Time on page collection

Bisko, through its WebSDK, provides functionality for collecting the time a user has spent on the specific page. This requires minimal change to the implementation code.

For time on page collection to be enabled, the following line of code should be added to the code used to add Bisko WebSDK in a page.

bsk("time");

The implementation of Bisko WebSDK, with the time on page collection enabled would look like the following:

<!-- GjirafaTech Bisko Code -->
<script async src="https://bisko.gjirafa.net/web/{BISKO_ORGANIZATION_CODE}-sdk.js"></script>
<script>
  window.biskoQueue = window.biskoQueue || [];
  function bsk(){biskoQueue.push(arguments);}
  bsk('init', 'BISKO_PROPERTY_ID');
  bsk('time');
  bsk('event', 'pageview')
</script>
<!-- End GjirafaTech Bisko Code -->

The data collected from this functionality can be used in segment creation. Also by enabling time on page collection, the realtime analytics are enabled, and information regarding active users behaviour is made available through Realtime Analytics Dashboard

Record collection

Record events are custom events that you can create and collect in Bisko. Record events allow you to capture more specific actions that users take on your website or app, beyond the actions captured by the standard events. You can define the parameters associated with record events, and you can use them to collect custom metrics that are specific to your needs. For example, a record event could be used to collect the number of times a particular product was viewed on an e-commerce website, or the number of times a particular button was clicked.

In this section you can find some example code snippets for saving WebSDK events in Bisko:

var payload = {
  id: 1,
  name: "Apple IPhone",
  type: "product",
  description: "Black",
};

bsk("record", "recordAlias", payload);

The implementation of Bisko WebSDK on record collection for ArticleViews would look like the following:

var payload = {
  siteId: "SiteId value",
  pageId: "PageId value",
  articleId: "ArticleId value",
  articleTitle: "ArticleTitle value",
  articleExcerpt: "ArticleExcerpt value",
  articleTags: ["First value", "Second value", "Third value"],
  articleSections: ["First value", "Second value", "Third value"],
  articleMediaUrl: "ArticleMediaUrl value",
  articlePublishDateTime: "MM/dd/yyyy HH:mm:ss",
  articleAuthors: ["First value", "Second value", "Third value"],
  articleVersionId: "ArticleVersionId value",
  articleLabels: ["First value", "Second value", "Third value"],
  articleReadingTime: 1,
  articlePageIndex: 1,
  articlePageAlias: "ArticlePageAlias value",
  articlePages: 1,
  articleWordsCount: 1,
  articleCharactersCount: 1,
  articleSentencesCount: 1,
  sourcePage: "SourcePage value",
  rootLayoutId: "RootLayoutId value",
  rootLayoutVersionId: "RootLayoutVersionId value",
  articleLayoutId: "ArticleLayoutId value",
  articleLayoutVersionId: "ArticleLayoutVersionId value",
  themeId: "ThemeId value",
  themeVersionId: "ThemeVersionId value",
};

bsk("record", "articleviews", payload);

The implementation of Bisko WebSDK on record collection for Player would look like the following:

var payload = {
  playerId: 1,
  volume: 25,
  subtitleEnabled: true,
  displayScreen: "Normal",
  mode: "Theater Mode",
  autoplay: "ON",
  mute: false,
};

bsk("record", "player_action", payload);

The implementation of Bisko WebSDK on record collection for E-commerce would look like the following:

var payload = {
  id: 1,
  name: "Chanel perfume",
  type: "product",
  description:
    "In Parfum form, the fragrance full of contrast, with notes of Pink Pepper, Jasmine.",
  category: ["Perfume", "Fragrance"],
  expirationDate: "04/06/2022",
  imageUrl: "https://image.com/chanel",
  keywords: ["chanel", "chance"],
  value: "140",
};

bsk("record", "product_view", payload);

The implementation of Bisko WebSDK on record collection for Search would look like the following:

var payload = {
  id: 1,
  content: "MacBook",
  contentCharactersCount: 22,
  keywords: ["Laptop", "Apple", "Mac", "IOS"],
  resultIds: [13127, 95314, 72365],
};

bsk("record", "search", payload);

Add Bisko to your site

Setup​

User identification​

User consent

Event collection

Event parameters​

General examples​

Article event examples​

Video event examples​

E-Commerce event examples​