Forem: JullSanders

A Simple Telegram Time Tracker Bot Creation

JullSanders — Mon, 30 Mar 2020 13:01:48 +0000

Everyone has Telegram nowadays. All of us use this messenger daily — it’s convenient, easy to use, intuitive, secure, and of course we all love stickers. Besides the personal messaging, we often use group chats — with family, friends and colleagues. In addition to live ordinary users, there are also bots in Telegram. They are created to automate replies, meaning the bot responds to specific messages — commands and performs certain actions. An action can be either a simple greeting in response, or a chain of certain questions and answers to perform specific logic operations.

Personally I, for instance, constantly use @vkmusic_bot_news chatbot. It’s a simple bot for music search and listening. A user sends a message with the name of a composition or the author and the bot provides variants, which match the request.

In my example I asked for a song «show must go on» and received several variants to choose from. Having chosen the first variant, I received a track in the next message. It’s convenient that you can listen to music right in the chat with the bot. In such a way a bot can fully substitute a third-party app, like a player on your phone. You just search and listen to the music right away.

So we can see that the telegram chatbots are rather convenient and multifunctional feature of the messenger. That’s why this article is devoted to a simple chatbot creation. I decided to make a primitive time tracker to show you an example. It’s the simplest case of interaction with the telegram API.

Simple Telegram chat bot creation

So let’s start.

You can find the docs here: https://core.telegram.org/bots/api.

First, you should create and register the bot in the Telegram. Let’s find the all-bots Father @botfather . It’s a bot for bot registration.

We inform him that we want to create our own chatbot:

/newbot

With the next request he asks to create a name for the bot. Since my bot will track time, I give him the corresponding name and write:

timeTrackerBot

The next step is to create bot’s username (it will be used for search @username). The condition is — the username must end in bot or _bot. I write:

my_time_tracker_bot

It’s ready! We receive a token in response, it means that we have registered a new chat-bot.

Development

To start I decided to look what libraries the internet offers to us. The variants are multiple. The full list of the proposed options can be found here . My choice was TelegramBotApiBundle for Symfony. We install it:

composer require borsaco/telegram-bot-api-bundle

and proceed.

The bundle supports the work with several bots at a time, besides, there is the option of adjustment (sending only to the developer) and working through proxy. For the test example, we do not need much, so we remove what we do not need.

config/packages/telegram.yaml

I also carried the token out into the variable APP_TELEGRAM_TOKEN в .env

A bit of Theory

Telegram API, so to say works in two modes: you can get updates from the server through getUpdates() method or adjust the webHook. The first variant is good, because it’s extremely simple, but the drawback of it that you should constantly request server if there are any updates. The webHook variant allows not to think about how to get the updates, but to focus on their rendering. In this case Telegram will send the updates itself to the URL we’ll indicate.

The advantage of the second approach is obvious).

To register a Webhook we’ll do the following:

$bot = $botService->getBot('timeTracker');
$bot->setWebhook(
    [
'url'=>'https://myWebSite.com/webhook'
]
);

Webhook in the url value is a route, which we’ll make a bit later.

$botService — is an object of the service Borsaco\TelegramBotApiBundle\Service\Bot, which can be injected in any place of the project.

Important: telegram API only supports sending to https!

Let’s now check our Webhook: if you send a message to our telegram bot, it will send us such a data set in response:

{
  "update_id": 21406673,
  "message": {
    "message_id": 24,
    "from": {
      "id": 701891111,
      "is_bot": false,
      "first_name": "aleksei",
      "language_code": "ru"
    },
    "chat": {
      "id": 701891111,
      "first_name": "aleksei",
      "type": "private"
    },
    "date": 1580672814,
    "text": "/help",
    "entities": [
      {
        "offset": 0,
        "length": 5,
        "type": "bot_command"
      }
    ]
  }
}

We are interested in the part with the message text. In this case, it is clear that I sent the bot «/ help».

Naturally, he does not answer.

The presence of entities in the response indicates that the message was perceived by the bot as a command (everything that starts with a slash and is written in Latin is a command for Telegram).

Let’s create a controller. It will be the entry point for the requests from the Telegram API where to the updates will come.

For convenience, I put all the logic into the MessageProcessor service, where I pass the string received from Telegram.

The essence is simple — there are 4 commands: help, start, stop, report.

To the «help» message or any other one that does not fit into this list, the bot should return a message with a list of the commands available.

Each command presupposes specific behavior.

There are also 2 situations when the answer will tell the user that this action is prohibited at the moment (until the time tracker is stopped — you can’t start a new one. Accordingly, while there is no activity — you can’t stop anything either).

I have added the following entities:

User, which has the fields name, telegramId and collection timeLines,
TimeLine, which has a starting date and an end date: startedAt, stopedAt.

That is, a user can have multiple timelines (which have a start time and a stop time).

We get a json string, and the first thing I do is decode the string and get the object.

$response = \json_decode((string)$telegramUpdate);

Further on, I check if there is such a user in the database (the data about the user who wrote to the bot is taken from response-> message-> from). If there is no such a user, we create it.

Since we want that «help» and «/ help» commands to be perceived by the bot in the same way, we translate the text of the message from the user into lower case and delete the normal and the back slashes.

$messageText = mb_strtolower($response-&gt;message-&gt;text);
$messageText = str_replace([&rsquo;\\&rsquo;, &rsquo;/&rsquo;], &rsquo;&rsquo;, $messageText);

Now we check the received command — if it’s included in the list of commands that we can process. And now, based on what we’ve got, we send a reply.

$messageCommand = $this-&gt;isSupports($messageText) ? $messageText : false;

If it’s either a «start» or «stop» command, we create a TimeLine for this user or end the current one accordingly and inform the user about it.

If this is a «report», we calculate the time in all timeline for today and send the total number of hours and minutes to the user. We send the messages with the sendMessage method, which accepts an array of parameters. Required parameters are: ’chat_id’ and ’text’.

A complete list of commands can be found here .

Since this is a test case, I limited myself to a simple switch / case for command selection.

switch ($messageCommand) {
  case self::HELP_COMMAND :
     $this->bot->sendMessage(['chat_id' => $user->getTelegramId(),      'text' => self::ANSWERS[self::HELP_COMMAND]]);
     break;
  case self::START_COMMAND :
     if ($this->timelineService->doesActiveExist($user)) {
        $this->bot->sendMessage(['chat_id' => $user->getTelegramId(), 'text' => self::BAD_ANSWERS['existNotStoppedTimeLine']]);
        break;
     }
     $this->telegramService->startTimeForUser($user);
     $this->bot->sendMessage(['chat_id' => $user->getTelegramId(), 'text' => self::ANSWERS[self::START_COMMAND]]);
     break;
  case self::STOP_COMMAND :
     if ($this->timelineService->doesActiveExist($user)) {
        $this->bot->sendMessage(['chat_id' => $user->getTelegramId(), 'text' => self::ANSWERS[self::STOP_COMMAND]]);
        break;
     };
     $this->bot->sendMessage(['chat_id' => $user->getTelegramId(), 'text' => self::BAD_ANSWERS['timeLineNotFound']]);
     break;
  case self::REPORT_COMMAND :
     $timeForToday = $this->timelineService->getTodayTotalByUser($user);
     $this->bot->sendMessage(['chat_id' => $user->getTelegramId(), 'text' => \sprintf(self::REPORT_COMMAND, $timeForToday)]);
     break;
  default:
     $this->bot->sendMessage(['chat_id' => $user->getTelegramId(), 'text' => self::ANSWERS[self::HELP_COMMAND]]);
}

General view of the service is like this:

Thus, we’ve got a bot, which can help you track the time in course of the day.

Conclusion

To draw a line, we can safely say that the Telegram API is quite functional and easy to master. A big advantage is good documentation and the ready-made libraries available for the usage.

Originally published at Stfalcon.com .

Postman: a Quick Start for Development and Testing

JullSanders — Fri, 27 Mar 2020 14:19:42 +0000

This article is intended to speed up and simplify the process of mastering the Postman tool basic functionality.

The company positions its product as an API development platform.

But why does everyone love Postman platform?

— This is a powerful API testing and development tool, which at the same time has a simple and intuitive interface. If this is the first time you open this program and know the difference between POST and GET, then you can easily send your first request. However, there are some nontrivial tricks which make life much easier.

Postman requests

So let’s start ( get postman app ).

We look for the necessary button (1) in the upper central part and create a workspace (or select from the existing ones as I do). The notion of a workspace comprises grouping of your projects —it may be a folder or desktop, if you want.

Then we click plus (2) and create a request tab.

Everything is extremely simple with a GET request: we set the url, add parameters (you can «turn on» and «turn off» the parameters), press send and see the answer in the bottom half of the screen (on the server, I just return the html page and present all the incoming parameters in json format). Switching between tabs in the response area, we can find any information and even switch between views and output formats.

To the right of the Send button there is a Save button. At the attempt of saving, postman will ask you to specify/create a collection. A collection is a group of requests in the workspace (sorted, for example, by project). I created a test_collection collection. We save your request there.

Postman environment

Let’s proceed further.

There is the concept of environment in postman — it’s a set of variables that can be assigned a value and used during your work. The environments may be multiple (for sales, for stages, for different versions — for anything). The environment is tied to the operational environment: each operational environment has its own postman environment.

We click on the gear in the upper right corner and create an environment.

I have created a local_test_env environment with 2 variables: host and username. There are 2 columns for the variable value. The only difference is that if you share your project with your team, then the value from the first column will be shared, and the queries that you make on your PC will use the second column. Your postman account synchronization also occurs from the first column.

I usually duplicate them — it’s better to make it a habit to fill everything in, and replace the data in case of necessity.

We select our environment as active (there is a drop-down list to the left of the gear).

Let’s send POST using variables. We should add a tab and select the type of POST request. We want to use the host variable from our environment. Variables are written in double curly braces. We put the braces and begin to write the name of the variable, postman will suggest us to select a variable from the current environment. Let’s choose. Since this is a POST request, we proceed to the body tab (under the address bar) and add the username parameter, the value for which will be a variable. I added several more parameters for illustrative purposes, the server will return the sum of them.

The server returned a json line to us.

In Postman, we can interact with the received result, programmatically send requests, and write tests.

Some words about tests

We open the console with a combination of cmd + alt + c (ctrl + alt + c for Windows). I made one request and see its logs. In addition, you can output something to the console with the following command:

console.log("something")

Tests are written on the Tests tab. I will give you a few examples of simple tests, and then we’ll see how to work with them.


pm.test("Status code is 200", function () {
    pm.response.to.have.status(200);
});

This is a common anonymous function. In this case, we say that the answer should have a status of 200.

Due to the fact that we get a json line in the server response, we can parse this into a variable. Let’s do it with the following line:

var jsonData = pm.response.json();
Then we use a new variable:

pm.test("check number equal 9 ", function () {
pm.expect(jsonData.total).to.eql(9);
});
In this example, we expect that total in jsonData will be equivalent to 9.

Now let’s try to compare the received value of the field «name» from jsonData with the username variable we have in our environment.

You can get a variable from the environment like this:

pm.environment.get('username')

Now an equivalence test:

pm.test("check name equal variable username", function () {
    pm.expect(jsonData.name).to.eql(pm.environment.get('username'));
});

You can not only read, but also write in the environment.

We are trying to get the variable “total” from the environment (it is not there yet).

var sum = pm.environment.get('total');

Since we did not get anything from the environment, there will be nothing in «sum» either. We create a «total» in the environment and write in there the value obtained from jsonData.total.

if (!sum) {
    pm.environment.set('total', jsonData.total);
}

Now let's see what has happened:

All the tests except the first one have passed. The server returns the code 201 to us, while we expect 200. Our variable is in the environment, so everything works.

Now, when you have some understanding of postman, let’s try to send a request, or rather a few.

Task: to send a certain number of requests, each time changing a parameter.

First we create a new collection of loop requests,
Then we create a POST request,
After that body we add the parameter «digit», which will change into the request (we take the value from the environment).
In the pre-request Script tab, we add the following code:

var digits = pm.environment.get('digits');

if (!digits) {
    digits = ["2", "4", "5", "22", "13", "6"];
}

console.log("digits: " + digits);

var currentDigit = digits.shift();

pm.environment.set('digit', currentDigit);
pm.environment.set('digits', digits);

(We check if there is a variable «digits» in the environment, and create it, if there is no such a variable. We output the array «digits» to the console before the request. Next, we take the first element from «digits», removing the value from the array itself. And set the value in the environment for «digit» and «digits». There is one first element less in digits already.)

In the tab «Tests», we write the following:

var digits = pm.environment.get('digits');
var digit = pm.environment.get('digit');

console.log("server got digit = " + pm.response.json().digit);

if (digits && digits.length > 0) {
    postman.setNextRequest("loop request");
} else {
    postman.setNextRequest(null);
    console.log("stop");
    pm.environment.unset("digits");
    pm.environment.unset("digit");
}

(We take «digit» and «digits» from the environment and put some information into the console. If «digits» is not empty, we specify the following request setNextRequest and pass the current request as a parameter. Otherwise, we say that nothing else should be done, clear the environment variables and print the line «stop» in the console.)

After all that we open Runner (in the upper left corner), select our new collection and our loop request, select the environment and click Run loop.

In the runner, we see that 6 requests have been completed.

We then open the console and watch the logs:

Conclusion

We tested some of the of Postman’s features in practice, made sure that it’s really a very convenient and multi-functional development platform that simplifies the processes of development and API testing.

Comprehensive documentation can be found here .

Originally published at Stfalcon.com

A Quick API Platform Hands On Review for Symfony App Development

JullSanders — Tue, 10 Mar 2020 15:37:37 +0000

There are many ways of REST API implementation in a symfony app . One of them is REST API Patform. We get REST API protocol support, documentation and Swagger UI with the possibility to test endpoints out of the box.

Quick Start

We add API platform into the application.

composer req api

Swagger UI is active by default and available at http://localhost/api:

While no end point is defined (the operation in API Platform terms), it’s simple to do it. You should only add annotation @ApiResource to the entity.


<?php

declare(strict_types=1);

namespace App\Entity;

...

/**
 * Customer.
 *
 * @ORM\Entity()
 *
 * @ApiResource()
 */
class Customer
{
    /**
...

A full set of CRUD operations has appeared. All the operations are divided into 2 groups:

collection operations — operations with the collection of elements
item operations — operations with a data element.

Collection operations:

GET - to get a list of elements;
POST - to add an element to the collection.

Item operations:

GET - to get an element by ID;
PUT - to change an element;
DELETE - to delete an element from the collection;
PATCH - to partly substitute the element.

Element configuration can be described in the annotations, xml or yaml files. The yaml files location is defined by the path parameter of the configuration file config/packages/api_platform.yaml

api_platform:
    mapping:
        paths:
            - '%kernel.project_dir%/src/Entity'
            - '%kernel.project_dir%/config/api_platform'

If it’s needed, we can restrict the set of the operations with a list:

<?php

declare(strict_types=1);

namespace App\Entity;

...

/**
 * Customer.
 *
 * @ORM\Entity()
 *
 * @ApiResource(collectionOperations={"get","post"},itemOperations={"get","delete"})
 */
class Customer
{
    /**
...

or in a yaml file:

# config/api_platform/customer.yaml
App\Entity\Customer:
  itemOperations:
    get: ~
    delete: ~
  collectionOperations:
    get:
    post: ~

Per-page collection display

The elements collections support per-page layout.

Validation

If it is necessary to check the input data, it is enough to add an entity property validator — the API platform generates an error message:

...
    /**
     * @var string
     *
     * @ORM\Column(type="string", length=50, nullable=false)
     *
     * @Assert\NotBlank()
     * @Assert\NotNull()
     * @Assert\Length(max="50")
     */
    private $name;
...

with a line of more than 50 characters we’ll get an error:

{
  "@context": "/api/contexts/ConstraintViolationList",
  "@type": "ConstraintViolationList",
  "hydra:title": "An error occurred",
  "hydra:description": "name: This value is too long. It should have 50 characters or less.",
  "violations": [
    {
      "propertyPath": "name",
      "message": "This value is too long. It should have 50 characters or less."
    }
  ]
}

Related Objects

To provide the uniqueness of object identifiers API platform uses IRI (Internationalized Resource Identifier). Each object’s IRI coincides with the GET request for this object /api/customer/123. The same type of identifier is used for the requests of objects adding and editing.

Let’s add a new entity related to the Customer entity.

...
/**
 * Message.
 *
 * @ORM\Entity()
 *
 * @ApiResource()
 */
class Message
{
    ...

    /**
     * @var Customer
     *
     * @ORM\ManyToOne(targetEntity="App\Entity\Customer", inversedBy="messages")
     * @ORM\JoinColumn(nullable=false)
     *
     * @Assert\NotBlank()
     * @Assert\Type(type="App\Entity\Customer")
     */
    private $createdBy;
    ...
}

The body of the request to add a new item will look like this:

{
   ...
   “createBy”: “/api/customer/123”,
   ...
}

The list of the collection items will look like this:

{
  "@context": "/api/contexts/Customer",
  "@id": "/api/customers",
  "@type": "hydra:Collection",
  "hydra:member": [
    {
      "@id": "/api/customers/1",
      "@type": "Customer",
      "id": 1,
      "name": "name 1",
      "email": "test@test.com",
      "messages": [
        "/api/messages/3",
        "/api/messages/2",
        "/api/messages/1"
      ]
    },
  ],
  "hydra:totalItems": 1
}

As you can see the list of messages is presented as an array of IRI strings:

   "messages": [
        "/api/messages/3",
        "/api/messages/2",
        "/api/messages/1"
      ]

The request http: // localhost / api / messages / 1 will provide such result:

{
  "@context": "/api/contexts/Message",
  "@id": "/api/messages/1",
  "@type": "Message",
  "id": 1,
  "createdBy": "/api/customers/1",
  "title": "title 1",
  "text": "message 1"
}

Using serialization groups, we can display not only the IRI of the object, but also the data of the nested object in case of necessity. To do this, for the item operation GET, we’ll specify the serialization group:

# config/api_platform/message.yaml
App\Entity\Message:
  itemOperations:
    get:
      normalization_context:
        groups:
          - message
    put: ~
    delete: ~
  collectionOperations:
    get: ~
    post: ~

We’ll add the group to the properties of the Message and Customer objects. Now the result of the same query will be different.

{
  "@context": "/api/contexts/Message",
  "@id": "/api/messages/1",
  "@type": "Message",
  "id": 1,
  "createdBy": {
    "@id": "/api/customers/1",
    "@type": "Customer",
    "id": 1,
    "name": "customer 1"
  },
  "title": "title 1",
  "text": "message 1"
}

Filters

API platform has a built-in filter mechanism:

Doctrine ORM and Mongo ODM

Search filter (string fields);
Date filter;
Boolean filter;
Range filter (numeric fields);
Exists filter (nullable values);
Order filter (collection’s sort order changes).

Elasticsearch

Ordering filter;
Matching filter;
Term filter.

Serialization filters

Group filter (defines a list of serialization groups for the query result);
Property filter (defines the list of displayed properties).
There is also a possibility to define the user filters types.

Let’s add the string fields filter for example:

...
/**
 * Message.
 *
 * @ORM\Entity()
 *
 * @ApiResource()
 * @ApiFilter(SearchFilter::class, properties={"title": "iend", "text": "partial"})
 */
class Message
{
...

We have added 2 filters

by title field — it will search for all the elements, which have the title field ending as in the search sample. The search is case independent (symbol i in the beginning of the filter type name).
by text field — will search for all the elements having a search sample in the text field. The search depends on case.

Data Transfer Objects (DTO) Usage
In case of necessity we can use not the entities directly, but DTOs. We have to take 3 steps for this.

To describe DTOs input and output classes.
Indicate the classes as input and output in our entity parameters.
Describe Data Transformer classes for entity into DTO transformation and back.
Input DTO:

...
/**
 * MessageInputDto.
 */
class MessageInputDto
{
...
}
...

Output DTO:

...
/**
 * MessageOutputDto.
 */
class MessageOutputDto
{
...
}
...

Adding DTO classes into entity description:

/**
 * Message.
 *
 * @ORM\Entity()
 *
 * @ApiResource(
 *     input=MessageInputDto::class,
 *     output=MessageOutputDto::class
 * )
 */
class Message
{
...

Data Transformer for input DTO:

/**
 * MessageInputTransformer.
 */
class MessageInputTransformer implements DataTransformerInterface
{
    /**
     * {@inheritDoc}
     */
    public function transform($object, string $to, array $context = []): Message
    {
        $message = new Message();
        ... 

        return $message;
    }

    /**
     * {@inheritDoc}
     */
    public function supportsTransformation($data, string $to, array $context = []): bool
    {
        return Message::class === $to && $data instanceof MessageInputDto;
    }
}

Data Transformer for output DTO:

/**
 * MessageOutputTransformer.
 */
class MessageOutputTransformer implements DataTransformerInterface
{
    /**
     * {@inheritDoc}
     */
    public function transform($object, string $to, array $context = []): MessageOutputDto
    {
        $dto = new MessageOutputDto();
        ... 

        return $dto;
    }

    /**
     * {@inheritDoc}
     */
    public function supportsTransformation($data, string $to, array $context = []): bool
    {
        return MessageOutputDto::class === $to && $data instanceof Message;
    }
}

Such an approach has a drawback – DTO validation won’t work. To correct this, you should change the transformer class input DTO.

/**
 * MessageInputTransformer.
 */
class MessageInputTransformer implements DataTransformerInterface
{
    private $validator;

    /**
     * @param ValidatorInterface $validator
     */
    public function __construct(ValidatorInterface $validator)
    {
        $this->validator = $validator;
    }

    /**
     * {@inheritDoc}
     */
    public function transform($object, string $to, array $context = []): Message
    {
        $this->validator->validate($object);

        $message = new Message();
        ... 

        return $message;
    }

    /**
     * {@inheritDoc}
     */
    public function supportsTransformation($data, string $to, array $context = []): bool
    {
        return Message::class === $to && $data instanceof MessageInputDto;
    }
}

User controllers

In case none of the methods described above allows us to get the desirable result, we have an opportunity to use our own controller.

Variant 1

/**
 * CustomerAction.
 */
class CustomerAction
{
    private $customerService;

    /**
     * @param CustomerService $customerService
     */
    public function __construct(CustomerService $customerService)
    {
        $this->customerService = $customerService;
    }

    /**
     * @param Customer $data
     *
     * @return Customer
     */
    public function __invoke(Customer $data): Customer
    {
        $this->customerService->handle($data);

        return $data;
    }
}

The name of the method parameter is __invoke, there should obligatory be $data. Otherwise it would be empty. Let’s add the controller into the entity configuration.

/**
 * Customer.
 *
 * @ORM\Entity()
 *
 * @ApiResource(itemOperations={
 *     "get",
 *     "delete",
 *     "customer_action"={
 *          "method"="POST",
 *          "path"="/api/customer/{id}/action",
 *          "controller"=CustomerAction::class,
 *     }
 * })
 */
class Customer
{

Variant 2

/**
 * Customer.
 *
 * @ORM\Entity()
 *
 * @ApiResource(itemOperations={
 *     "get",
 *     "delete",
 *     "customer_action"={"route_name"="customer_action_route"}
 * })
 */
class Customer
{

And we add the controller class:

/**
 * CustomerController.
 */
class CustomerController
{
    /**
     * @Route("/api/customer/{id}/action", name="customer_action_route", methods={"POST"})
     *
     * @param Customer $customer
     *
     * @return Response
     */
    public function executeAction(Customer $customer): Response
    {
        ...


        return new Response(...);
    }
}

User data sources

Data access with Doctrine ORM and Elasticsearch-PHP are built in as standard in the API Platform. Doctrine ORM is active immediately after installation; Elasticsearch-PHP can be switched on in the configuration file.

For the other data sources options, we can define our own data source by adding a new class. We should implement the CollectionDataProviderInterface, RestrictedDataProviderInterface interfaces for the collection provider or ItemDataProviderInterface, RestrictedDataProviderInterface for the collection item provider. Another provider is involved in data modification, it implements the ContextAwareDataPersisterInterface interface.

Impressions, findings...

API Platform is much more extensive than it was revealed in this review. We did not mention here the automated generation of documentation and json schemes, serialization management, security and access control, platform own extensions, integration with Symfony Messenger and other features. Full description can be found in the official documentation at https://api-platform.com/docs/. The purpose of this article was the hands-on review of the tool.

API Platform includes a large toolkit for writing a REST API which will allow you implement most of the tasks that arise during the REST API Backend writing with a minimum amount of code. At the same time all the actions, which are beyond CRUD should be realized independently in the form of standard controllers.

Originally published at Stfalcon.com

Awareness API: What Is It and How It May Help?

JullSanders — Sun, 01 Mar 2020 12:44:24 +0000

Every year our life and daily routine are more and more closely connected with mobile phones. Modern life is extremely dynamic and that’s why mobile apps should match the users’ activity. Awareness API exists just for the purpose.

What is API in app development and how it may help?

Google Awareness API allows us to monitor the user activity, it’s possible at a certain moment as well as while the app operates.

API allows us to get the data as to the:

Headphones state (plugged/unplugged);
Location;
Activity (stands, drives, runs, walks);
Time (local user’s time o set certain frames);
Reaction to beacons.

There are plenty of situations, where these features can be used. If it’s a sports app for running, for instance, it’s possible to find out when the user started his training, and if it’s a restaurant app, there is an opportunity to notify the user about special offers or invite him to visit the restaurant when he is somewhere nearby.

Awareness API is divided into two parts, namely:

*Snapshot API *— it allows to get the live info at a certain moment
*Fence API *— it registers one or several triggers, which inform us if the user is now active or not.
To better understand it, please find the example of an app code here: https://github.com/stfalcon-studio/GoogleAwarenessDemo .

To begin we should get an API key, here is a perfect guide from Google - https://developers.google.com/awareness/android-api/get-a-key.

As soon as we’ve got the key, we should add it to the manifest file of your project. It’s like this:

 <meta-data
    android:name="com.google.android.awareness.API_KEY"
     android:value="YOUR_API_KEY"/>
</application>

Now you have only to add dependency to gradle:

implementation 'com.google.android.gms:play-services-awareness:{last_version}'

Don’t forget about the permissions, you should add the following to the manifest for the purpose:

<uses-permission android:name="com.google.android.gms.permission.ACTIVITY_RECOGNITION"/>
    <uses-permission android:name="android.permission.ACTIVITY_RECOGNITION"/>

*Don’t also forget about the permissions checking in the app.

That’s all, now you can use the possibilities of Awareness API in full.

Snapshot API

As it was already mentioned Snapshot API informs about the live status.

You should first initialize the SnapshotClient.

al snapshotClient = Awareness.getSnapshotClient(this)

Now we can get data about the user’s activity right at the moment.

Headphones

With a Snapshot API we can find the current state of headphones, whether they are plugged in or unplugged. It will be useful for sports apps development, for instance, to notify the user about his goal achievement, if his headphones are plugged in.

To get to know the headphones state, you should just call the function getHeadphoneState() and to get the result to add addOnSuccessListener, which will turn us back the HeadphoneStateResponse, with the headphoneState. Further on getState - will return us «1» or «2», which correspond to the status PLUGGED_IN or UNPLUGGED.

It’s also reasonable to add addOnFailureListener, which returns Exception if something has gone wrong.

Example:

private fun snapshotCheckHeadphones() {
        snapshotClient.headphoneState
            .addOnSuccessListener {
                snapshotHeadphonesContainer.text = it.headphoneState.toString(this)
            }
            .addOnFailureListener {
              handleSnapshotError(snapshotHeadphonesContainer, it)
            }
    }

toString - this is the expanding feature to make the code look simpler.

fun HeadphoneState.toString(context: Context): String {
    return context.getString(
        R.string.headphones_state,
        if (state == HeadphoneState.PLUGGED_IN) {
            context.getString(R.string.headphones_state_connect)
        } else {
            context.getString(
                R.string.headphones_state_disconnected
            )
        }
    )
}

Location

With the help of Snapshot API we can also find out the current user’s location.

The examples of the usage are numerous in this case, if for instance, the app has a list of some places, we can offer the user to visit this or that place if he is interested in it and is somewhere nearby.

To get location you should call getLocation() in OnSuccess we will get LocationResponse, which contains information about the user’s locale. We can get the info with getLocation(), which contains latitude, longitude, altitude and so on.

Example:

private fun snapshotGetLocation() {
        snapshotClient.location
            .addOnSuccessListener {
                with(it.location) {
                    snapshotLocationContainer.text = getString(
                        R.string.user_location,
                        latitude, longitude, altitude, accuracy
                    )
                } 
            }
            .addOnFailureListener {
                handleSnapshotError(snapshotLocationContainer, it)
            }
    }

*Location *- it’s a standard class of the Android SDK, so you can check the manual for the detailed description of all the available functions.

**Note: **don’t forget to add android permission ACCESS_FINE_LOCATION to the manifest as well as permission for checking.

User Activity

As it was already mentioned, Awareness API also allows to check the current user activity. It can be extremely useful in the fitness app development or some app with news. When the user does not move he can be offered to read some article.

The realization approach is the same: we need to call getDetectedActivity feature, which in case of success will turn us DetectedActivityResponse back. From it we can take data about the user activity. We have the following features available: getMostProbableActivity, which will return us the most probable activity and getProbableActivities, which will return us the list of possible activities sorted from the most probable one.

Activity has two parameters, namely:

Activity type — we use getType() for getting the type of activity, the example will be below.
Probability of the activity — which is got due to the getConfidence() feature — it will return int value from 0 to 100.

Example:

snapshotClient.detectedActivity
            .addOnSuccessListener {
                with(it.activityRecognitionResult) {
                    snapshotActivityContainer.text = getString(
                        R.string.user_activity,
                        mostProbableActivity.stateString(),
                        mostProbableActivity.confidence
                    )
                }
            }
            .addOnFailureListener {
                handleSnapshotError(snapshotActivityContainer, it)
            }

stateString - it’s the function of extension, which returns the text value of the activity type.

fun DetectedActivity.stateString(): String {
    return when (type) {
        0 -> "IN_VEHICLE"
        1 -> "ON_BICYCLE"
        2 -> "ON_FOOT"
        3 -> "STILL"
        4 -> "UNKNOWN"
        5 -> "TILTING"
        6, 9, 10, 11, 12, 13, 14, 15 -> type.toString()
        7 -> "WALKING"
        8 -> "RUNNING"
        16 -> "IN_ROAD_VEHICLE"
        17 -> "IN_RAIL_VEHICLE"
        18 -> "IN_TWO_WHEELER_VEHICLE"
        19 -> "IN_FOUR_WHEELER_VEHICLE"
        else -> type.toString()
    }
}

Fence API

Awareness API allows to put certain conditions and «listen» when the activity of the users coincides with it.

We can check:

The location of a user and check if he entered a certain area.
The user activity when he or she, for instance, has started/continues/stopped to walk, run, drive, etc.
Headphones state, when they have been plugged in or unplugged.
When the user has entered the area of beacons operation.
Time frames, when the user is in a certain timeframe of a certain weekday.

We can also combine several features, using the operators AND, OR or NOT. We can for instance check the following:

The user runs with headphones plugged in.
The user drives and has entered a certain area.
The headphones are plugged in in an evening time,without activity (so the user is likely in bed).

How to start using Fence.

Firstly, to get the information about the fence state change we should create our own BroadcastReceiver.

Like this for example:

inner class FenceReceiver : BroadcastReceiver() {

        override fun onReceive(context: Context, intent: Intent) {
            val fenceState = FenceState.extract(intent)
            if (fenceState.fenceKey == FENCE_KEY) {
                when (fenceState.currentState) {
                    FenceState.TRUE -> {
// We've entered the fence                    
}
                    FenceState.FALSE -> {
                        // We're not in the fence
                    }
                    FenceState.UNKNOWN -> {
                        // Something went wrong
                    }
                 }
            }
        }
    }

It will receive all the changes which refer to our registered fences. For instance, we wait till the user plugs the headphones in:

We check if the FENCE_KEY, which came coincides with the one we have registered (what’s it and where it’s got from we’ll see below).
Then we check the state, if it’s TRUE, then the headphones are plugged in if it’s FALSE, then vice versa and the UNKNOWN state means an error has occurred and the system fails to understand what the headphones’ status is.
**Note: **don’t forget to register FenceReceiver in onCreate

registerReceiver(fenceReceiver, IntentFilter(FENCE_RECEIVER_ACTION))

And to disconnect it at onDestroy:

unregisterReceiver(fenceReceiver)

For the system to send us changes, we should create PendingIntent.

val intent = Intent(FENCE_RECEIVER_ACTION)
        val mPendingIntent =
            PendingIntent.getBroadcast(this, 0, intent, 
PendingIntent.FLAG_UPDATE_CURRENT)

Then we should define which activity we are interested in. Let’s take the headphones plugged in and running for example.

val fence = AwarenessFence.and(HeadphoneFence.during(HeadphoneState.PLUGGED_IN), DetectedActivityFence.during(DetectedActivityFence.RUNNING))

Now we gather it all together and register.

fenceClient.updateFences(
            FenceUpdateRequest.Builder().addFence(
                FENCE_KEY,
                fence,
                mPendingIntent
            ).build()
        )
            .addOnSuccessListener {
                //Fence created
            }
            .addOnFailureListener {
// Error while creating
            }

FENCE_KEY is necessary for us to distinguish various registered fences.

You should also not forget about fence deleting when we have finished working with it. We use removeFence() for the purpose, where the necessary FENCE_KEY is rendered as a parameter.

fenceClient.updateFences(
            FenceUpdateRequest.Builder()
                .removeFence(FENCE_KEY).build()
        )

*if it’s necessary, you can also add successListener and failureListener for deleting.

Now knowing how to create and delete fence we can look at what types of fence exist.

Headphone Fence

With headphones everything is alike and we have the following fences:

AwarenessFence headphonesPluggedInFence = HeadphoneFence.during(HeadphoneState.PLUGGED_IN;
AwarenessFence headphonesUnpluggedFence = HeadphoneFence.during(HeadphoneState.UNPLUGGED;

Location Fence

We can create the so-called «locations» and as soon as the user enters them we’ll know about it. We can check if he has entered/left a certain area or stays in it.

You need to specify the data about the latitude, longitude, and radius of the location (for checking if the user is inside the area, you should also indicate how many milliseconds should a user stay in it).

AwarenessFence inLocationFence = LocationFence.in(
latitude, longitude, radius, timeInMillis); 
AwarenessFence exitingLocationFence = LocationFence.exiting(
latitude, longitude, radius); 
AwarenessFence enteringLocationFence = LocationFence.entering(
latitude, longitude, radius);

Activity Fence

We can also get to know when a user has started, continues or finished a certain activity. The class DetectedActivityFence, is used for the purpose, it has the starting, during and stopping features. The type of activity is added to these features as a parameter. Let’s for example create fences for all running states:

AwarenessFence running = DetectedActivityFence.during(DetectedActivity.RUNNING);
 AwarenessFence startRunning = DetectedActivityFence.starting(DetectedActivity.RUNNING);
 AwarenessFence stopRunning = DetectedActivityFence.stopping(DetectedActivity.RUNNING);

Time Fence

We can create fence for a certain period of time or a certain day.

AwarenessFence workingHoursFence = TimeFence.inInterval(startTime, endTime);
AwarenessFence fridayFence = TimeFence.inFridayInterval(
                                      timeZone, startTime, endTime);

That’s all.

We have had an overlook what an API is and how to use Fences and Snapshots. Thanks to them we can create more flexible apps, which facilitate the user’s usage of the application.

Originally published at https://stfalcon.com .

What’s New in Watch OS 6? Stand-Alone WatchOS Application with SwiftUI.

JullSanders — Mon, 17 Feb 2020 12:22:36 +0000

Last year on the WWDC 2019 Apple has announced iOS 13, watchOS 6, macOS X Catalina and a lot more. Until now a lot has been said about all those shiny new things. A lot of people suggest the latest WWDC be an as big step forward as the one during which Swift was introduced.

To my mind, the biggest changes do affect watchOS. Let’s face it, SwiftUI is available only since iOS 13, watchOS 6 and macOS Catalina and most of the developers would like to preserve compatibility with the previous version or two at least. Moreover, SwiftUI is not quite mature yet. There are still many problems during development as well as quite poor flexibility of the new framework. This means that we won’t see many SwiftUI iOS or macOS apps in the near future.

However, SwiftUI is just brilliant for watchOS. First of all, we usually do not need much functionality on a watch. Furthermore, the level of customization of views in WatchKit is not as high as in UIKit so moving to SwiftUI is not that painful. Finally, even now (November 2019) there are very few apps in watchOS AppStore which means that there’s enough space for you to implement your ideas.
In this article, I’d like to take a quick look at two major features of new watchOS update and create a stand-alone watchOS app using SwiftUI.

Application

Apple Watch is a great device that can currently track a lot of things: the distance you walk/run/swim, heart rate, standing hours, even volume level of the environment! But what about tracking something more enjoyable than sport? What about TV series for example? No kidding, it’s sometimes big trouble for me to remember which episode was the last and as soon as I watch series on different platforms I would like to have a third-party app to track this. Moreover, sometimes it’s just vital to remember which episode was last to avoid spoilers! :)
So let’s try to create a SeriesTracker app that will help you to remember at which season and episode you’ve left a particular TV series.
Let’s start with the project configuration. One should create a new Xcode project by choosing File:

New -> Project than switch to watchOS tab and select Watch App.

Then it’s important to choose SwiftUI for User interface in project configuration window.

Now we’ve got some basic project structure. Let’s clean it up a little by dividing all the files into different directories.

We won’t need Notifications, Complication and Resources so far in this article. We may surely use Assets.xcassets to add some pretty application icons or complications though :)

Let’s start with the acknowledgement of what an app should be able to do. We’ll store and display a list of series and some basic information about them. We’ll also provide the possibility to update information, remove series from the app and add new.

Model

{struct Series: Identifiable, Codable, Equatable {
    let id = UUID().uuidString
    let name: String
    var seasonNumber: Double = 1
    var episodeNumber: Double = 1
    var finishedWatching = false
}

First of all, we need to define a model.

Series structure contains id which is also required by the Identifiable protocol, name of the show, season and episode numbers and a bool value saying whether we’ve already finished watching it. Codable protocol is needed in order to store our shows in json format and Identifiable will soon be explained when it comes to the SwiftUI List structure.

final class DataStorage: ObservableObject {
    // MARK: - Singleton
    static let shared = DataStorage()
    // MARK: - Properties
    // Internal
    private let seriesPersistanceIdentifier = "com.stfalcon.series_tracker.series"
    // Data
    @Published var series: [Series]
    // MARK: - (Private) Init
    private init() {
        let storedSeriesData = UserDefaults.standard.data(forKey: seriesPersistanceIdentifier)
        self.series = DataStorage.decodedFromJson(storedSeriesData) ?? exampleSeries ?? []
    }
    // MARK: - Private logic
    func saveAll() {
        self.save(series, forKey: seriesPersistanceIdentifier)
    }
    private func save<T: Codable>(_ data: T, forKey key: String) {
        let rawData = DataStorage.encodedJsonRepresentation(of: data)
        UserDefaults.standard.set(DataStorage.encodedJsonRepresentation(of: rawData),
                                  forKey: key)
    }
    // MARK: - Private static utils
    private static func encodedJsonRepresentation<T: Codable>(of data: T) -> Data? {
        return try? JSONEncoder().encode(data)
    }
    private static func decodedFromJson<T: Codable>(_ data: Data?) -> T? {
        guard let data = data else { return nil }
        return try? JSONDecoder().decode(T.self, from: data)
    }
}

Now we should create some kind of persistence manager — DataStorage.

This class will have a shared singleton. We’ll keep series in the array and store them in user defaults. Sure usually it’s a bad idea to store big amount of data there. However, it’s just good enough for our example.

There are two unusual things about the DataStorage — ObservableObject and @Published. ObservableObject is a protocol an object has to conform to make itself available for SwiftUI to track and @Published annotation is a property-wrapper that makes particular property of object to be available for observing. We’ll take look at how it works later in this article.

Let’s also add a line of code to ExtensionDelegate to save our data to UserDefaults each time our app becomes inactive.

func applicationWillResignActive() {
    DataStorage.shared.saveAll()
}

Presentation

Now when we’ve done with the model let’s dive deeper in the presentation layer. There we have HostingController and ContentView so far. We’ll create our custom views and make one of them a subview of content view and then navigate to all the others. We will use HostingController as the only controller in the app and make our application something like a view-based.

Let’s start creating views from the most atomic ones. Our application will not be using any Internet connection so far so we won’t be able to download any pictures for our shows. However, we could still create a placeholder view with the first letter of the show’s title — LetterImageView.

struct LetterImageView: View {
    // MARK: - Data
    var letter: Character
    // MARK: - View
    var body: some View {
        ZStack {
            Rectangle()
                .size(CGSize(width: 200, height: 200))
                .foregroundColor(.gray)
            GeometryReader { geometry in
                Text(String(self.letter))
                    .font(Font.system(size: geometry.size.height / 2))
                    .bold()
            }
        }
        .clipShape(Circle())
    }
}
struct LetterImageView_Previews: PreviewProvider {
    static var previews: some View {
        LetterImageView(letter: "A")
    }
}

Every SwiftUI View is a structure conforming to the View protocol. Unlike UIKit all the views are structures in SwiftUI. That leads to having less problems with inappropriate use of OOP principles and helps us to avoid memory-management mistakes (like retain cycles for instance).

Only one stored property is needed by our view. It’s a character we want to display as the placeholder. Like every View our LetterImageView must provide computed property body that contains all the nested views. Most of SwiftUI views have an initialiser that has a closure parameter where we put all the nested views.

In this particular view we’ve used ZStack which is used to overlay the views: gray rectangle of fixed size and a label. Apart of ZStack, SwiftUI has also HStack and VStack (which are horizontal and vertical stacks). One should pay attention to that we wrap label inside of GeometryReader. This is made in order to adjust label’s font to the view’s size in case the whole view is scaled. Let’s also mark that we clip the stack to the shape of circle. SwiftUI provides us with a variety of shapes we can clip our views to.

Text(self.currentSeries.finishedWatching ? "Finished watching" : "In progress")
                    .font(.subheadline)
                    .foregroundColor(self.currentSeries.finishedWatching ? .gray : .green)

Looks quite declarative, doesn’t it? Sure and that is a huge advantage of SwiftUI. Another great thing about this framework is that code is now the only source-of-truth and there’s zero possibility that any configurations are overridden elsewhere as that could happen while using Storyboards.

We should also pay attention to the LetterImageView_Preview structure. It is used by the preview engine and should provide all the mocked data for the view.

Now we’ve got a placeholder.

// MARK: - Data
@EnvironmentObject var store: DataStorage
var seriesId: String
var seriesIndex: Int {
    store.series.firstIndex(where: { $0.id == seriesId })!
}
var currentSeries: Series {
    store.series[seriesIndex]

Let’s create a view that will display all the information about the show — SeriesDetailedView. Here we’ll need a storage as @EnvironmentObject, seriesId as stored property. We’ll also need some utilities like computed seriesIndex and currentSeries.

@EnvironmentObject as well as @ObservableObject and @State are the object-wrappers provided by SwiftUI. If any of @Published values of these objects are modified, changes are automatically tracked by the framework which invalidated view’s layout and launches UI reload. The main difference between these three annotations is that @EnvironmentObject is usually used for the objects shared for the whole application and provided by special method func environmentObject < B > (_ bindable: B) -> some View where B : ObservableObject of the View protocol; @ObservableObject is used for objects shared between a small number of views and provided via View’s initialiser; @State is used for the objects that are used in the context of single View and also provided via initialiser.

The body of the SeriesDetailView is quite straightforward so let’s only focus on some SwiftUI features that were not described yet.

As soon as all the UI is written in closures we can easily use conditional statements to include/exclude some views as well as make any parameters of UI configuration depend on model. It’s easy to see this in In progress label configuration.

Based on whether user has finished watching particular show we display different text on the status label and set the text’s color. Great declarative and quite convenient way to set up the UI.

Next we are going to create a view for editing current season and episode of the show and also the finishedWatching property. That means that we have to navigate to the next screen somehow. In SwiftUI there’s a simple way to do that.

NavigationLink(destination:
    EditSeriesView(
        seriesId: seriesId
    ).environmentObject(self.store)
) {
    Text("Update")

Here we create a NavigationLinkView and provide the destination view which is EditSeriesView in this case. We pass the seriesId and environment right in function parameter inline. We use trailing closure to specify the way NavigationLink should be drawn. In this case that would be a button Update.

var currentSeriesBinding: Binding<Series> {
        $store.series[seriesIndex]
    }

Although the interface of EditSeriesView is very simple, there is one major point to described. We’ll create another utility as computed property. Binding is used to reference an object or structure we want to update with the use of UI Controls. One should pay attention to that we use special $-syntax to make Binding from our ObservableObject. Now if we pass this binding to Slider, it will automatically update the particular series in our EnvironmentObject which will surely update the UI and keep it up to date. Simply talking as soon as user triggers the slider, the text of the label is automatically updated.

Text("Current season: \(Int(currentSeries.seasonNumber))")
                Slider(value: currentSeriesBinding.seasonNumber,
                       in: minValue...maxValue,
                       step: step)
                    .accentColor(.orange)

Here’s how it looks like on a device.

Now it’s time to create a list of all series in the app. SwiftUI List is a powerful analogue of UITableViewController from UIKit. It’s the main element in our SeriesListView. Later we’ll make this view the main view of our app providing it as a subview of the ContentView.

Let’s dive a bit deeper in the implementation of this view. Here we provide @EnvironmentObject that can be treated as some kind of datasource in this particular case. Moreover, we provide two @State properties. showInProgressOnly is used to filter away the shows that are currently not watched by user. newSeriesName will soon be used to store the name of newly added show.

struct SeriesList: View {
    // MARK: - Data
    @EnvironmentObject var store: DataStorage
    @State var showInProgressOnly = true
    @State var newSeriesName = ""
    // MARK: - View
    var body: some View {
        List {
            Toggle(isOn: $showInProgressOnly) {
                Text("In progress")
            }
            ForEach(store.series) { series in
                if !self.showInProgressOnly || !series.finishedWatching {
                    NavigationLink(
                        destination: SeriesDetailView(seriesId: series.id)
                            .environmentObject(self.store)
                    ) {
                        SeriesRow(
                            seriesId: series.id
                        ).environmentObject(self.store)
                    }
                }
            }
        }
        .navigationBarTitle("My Series")
    }
}

Usually we do not need to use ForEach for views in List. Passing datasource and closure with nested views to the list initialiser is good enough if we have dynamic cells only. In this case we have both — static cell with toggle that controls filtering and a number of dynamic cells displaying the shows. It’s important to emphasise that our datasource (the array of Series) is Identifiable as soon as Series is Identifiable itself. That makes List or ForEach able to distinguish between different models and enables them to work with reusable views. If Series wasn’t Identifiable we would have to provide an additional parameter id and specify #keyPath for the object’s primary key. It’s also nice to see how easily we can filter objects with the use of single conditional

statement (line 26).

Here’s how our list looks like on device.

Now we can display and modify our shows let’s give user the ability to remove ones.

To do this we should only create a method in our view that removes value from datasource based on the IndexSet and specify

.onDelete(perform: self.delete)

this function in onDelete for the ForEach element. Yes, that easy!

private func delete(at offsets: IndexSet) {
    store.series.remove(atOffsets: offsets)
}
TextField("Add new series", text: $newSeriesName, onCommit: {
                self.addNewSeries()
            })

Now let’s create an input for adding new series. We create a method that inserts a new value into the datasource and create a TextField which will modify newSeriesName @State and call addNewSeries function on commit.

Now we can add new TV series to our app.

Last but not least, most of the SwiftUI views are reusable all over the apple devices (watch, iPhone, Mac) and that is beautiful in case we want to develop a cross-platform application.

Conclusion

Although it’s true that SwiftUI is much, much more than these few things covered in this article, this tiny app is a brilliant example of how simple and straightforward the process of creating the stand-alone watchOS app is now. It truly looks like the beginning of the new era in mobile and wear software development.

The complete version of SeriesTracker can be found on the repo.

Originally published in Stfalcon.com.

Chat-app Creation in Real-Time Mode Using Vue.js, Nuxt.js, Node.js (Express), Socket.IO, Vue-Socket.IO, Vuetify.js Technologies.

JullSanders — Wed, 12 Feb 2020 12:21:45 +0000

Hello everybody. Recently I’ve got a desire to master the Socket.IO library and create a chat application, to strengthen theoretical knowledge with practice, so to say.

I actively use the technological stack which is implemented in the application in my work on commercial projects, but for Socket.IO.

It’s easy to inject the above-mentioned library into the already working project, but today I am going to speak about creating an app from scratch.
Let’s proceed, I do not like long forewords myself.

Setting up and installation of the Nuxt.js generic template.

You need to have Node.js installed, otherwise — install it.

If your NPM version is under 5.2 — install npx globally, using the rights of admin $sudo npm install -g npx.

After that create a project with the help of the following command:
$npx create-nuxt-app

Then a project configuration menu will appear (I used my project details):

Project name — “Nuxt-chat-app”
Description — “Simple chat with Nuxt.js”
Author’s name — “Petr Borul”
Package manager — “NPM”
UI framework — “Vuetify.js”
Server Framework — “Express”
Nuxt.js modules — “PWA”
Linting tools — “ESLint”
Test framework — “none” 10.Rendering mode — “Universal”

Let’s install SOCKET.IO: $npm install socket.io — save
I also used a wrapper for SOCKET.IO — Vue.SOCKET.IO.

In this library, you can call the websocket events and subscribe to them through the Vuex store, but for the hands-on review of the library, it is too implicit. That’s why I implemented the logic at the component level.

$npm install vue-socket.io --save

The full information on Nuxt.js folders’ structure you can find here.

The main points:

The folder pages contains views and routes. The framework reads all .vue files inside the folder and creates a router for the application.
The folder plugins contains JavaScript-plugins, which are run before the root application Vue.js creation (here our plugin socket.io will be resided).
The folder middleware contains the intermediate processing functions (the named ones are created in this folder, and if you want to specify the anonymous ones - you can declare them inside the component).
The file nuxt.config.js contains Nuxt.js user configuration.
The folder store contains the files of Vuex container. After index.js file creation in this folder, the container is activated automatically.

So, we have dealt with the main notions, let’s proceed to the app development itself. The folder contains the file index.js — we’ll change it a bit and take the server configuration to a separate file app.js.

const app = require('express')();
const server = require('http').createServer(app);
const io = require('socket.io')(server);
We’ll add server configuration to index.js:

index.js

const { app, server } = require('./app');

Then we’ll order Node.js to listen to the server configured:

server.listen(port, () => {
   consola.ready({
     message: `Server listening on http://${host}:${port}`,
     badge: true
   })
 })

Further on we create the file socket.client.js and add it to the folder plugins, we indicated the file extension ‘client’, because we need it only on the client-side (Here you can find all the info as to the plugin’s adjustments).

socket.client.js

import Vue from 'vue'
import VueSocketIO from 'vue-socket.io'

export default function () {
 Vue.use(new VueSocketIO({
   debug: false,
   connection: '/',
 }))
}

Now we’ll register it in the nuxt.config.js file:

plugins: [
   { src: '~/plugins/socket.client.js' }
 ],

From this point on you can refer to it in any component, using only the name of the file this.$socket.emit().

In the app.js file we’ll create two models of working with the data:

const users = require('../utils/users')();
const Message = require('../utils/message')();

message.js

class Message {
 constructor(name, text, id) {
   this.name = name;
   this.text = text;
   this.id = id;
   this.time = new Date().toString().slice(15, 24);
 }
}

module.exports = () => {
 return Message
}

users.js

class Users {
 constructor() {
   this.users = [];
 }

 addUser(user) {
   this.users = [...this.users, user]
 }

 getUser(id) {
   return this.users.find(user => user.id === id);
 }

 getUsersByRoom(room) {
   return this.users.filter(user => user.room === room);
 }

 removeUser(id) {
   this.users = this.users.filter(user => user.id !== id);
 }
}

module.exports = () => {
 return new Users()
}

We have finished with the server at this point and now we’ll proceed to the client side. In the folder store we’ll create index.js file and add the store

index.js

export const state = () => ({
 user: {},
 messages: [],
 users: []
})

export const mutations = {
 setUser(state, user) {
   state.user = user;
 },
 newMessage(state, msg) {
   state.messages = [...state.messages, msg];
 },
 updateUsers(state, users) {
   state.users = users;
 },
 clearData(state) {
   state.user = {};
   state.messages = [];
   state.users = [];
 },
}

Further on we’ll add a layout to the file index.js in folder layouts (I use UI library Vuetify.js because of the Material Design, which I like very much).

index.js

<template>
 <v-layout column justify-center align-center>
   <v-flex xs12 sm8>
     <v-card min-width="370">
       <v-snackbar v-model="snackbar" :timeout="3000" top>
         {{ message }}
         <v-btn dark text @click="snackbar = false">Close</v-btn>
       </v-snackbar>

       <v-card-title>
         <h1>Login</h1>
       </v-card-title>
       <v-card-text>
         <v-form ref="form" v-model="valid" lazy-validation @submit.prevent="submit">
           <v-text-field
             v-model="name"
             :counter="16"
             :rules="nameRules"
             label="Name"
             required
           ></v-text-field>
           <v-text-field
             v-model="room"
             :rules="roomRules"
             label="Enter the room"
             required
           ></v-text-field>
           <v-btn :disabled="!valid" color="primary" class="mr-4" type="submit">Submit</v-btn>
         </v-form>
       </v-card-text>
     </v-card>
   </v-flex>
 </v-layout>
</template>

<script>
import { mapMutations } from "vuex";

export default {
 name: "index",
 layout: "login",
 head: {
   title: "Nuxt-chat"
 },
 data: () => ({
   valid: true,
   name: "",
   message: "",
   id: null,
   nameRules: [
     v => !!v || "Name is required",
     v => (v && v.length <= 16) || "Name must be less than 16 characters"
   ],
   room: "",
   roomRules: [v => !!v || "Enter the room"],
   snackbar: false
 }),
 mounted() {
   const { message } = this.$route.query;
   if (message === "noUser") {
     this.message = "Enter your name and room";
   } else if (message === "leftChat") {
     this.message = "You leaved chat";
   }
   this.snackbar = !!this.message;
 },

 methods: {
   ...mapMutations(["setUser"]),
   submit() {
     if (this.$refs.form.validate()) {
       const user = {
         name: this.name,
         room: this.room,
         id: 0
       };
       this.$socket.emit("createUser", user, data => {
         user.id = data.id;
         this.setUser(user);
         this.$router.push("/chat");
       });
     }
   }
 }
};
</script>

When the submit () method is called, the form is validated, and in case of success, we send the event to the server this.$socket.emit().

We send a String with the name of the event to the server, and a callback function, after the fulfillment of which we get an ID and assign it to the user’s object, then we write it down to the state and send it to the chat page.

Let’s describe the event processing on the server:

io.on('connection', socket => {
 socket.on("createUser", (user, cb) => {
   users.addUser({
     ...user,
     id: socket.id
   })
   cb({ id: socket.id })
 });
})

1.The event “connection” is called when the user gets the connection with the server.

Then we subscribe to the event received from the client with the help of socket.on().
This function accepts the String and the callback function.
We add a new user to the users’ list and assign ID the corresponding ID socket for connection.
We pass the ID on to the client’s side.

Now we’ll create the layout of the default.vue file in the layouts folder, it’s set by default for all the components in the folder pages if the layout is not indicated (here you’ll find the detailed information).

default.vue

<template>
 <v-app>
   <v-navigation-drawer app v-model="drawer" mobile-break-point="650">
     <v-list subheader>
       <v-subheader>Users in room</v-subheader>

       <v-list-item v-for="(u, index) in users" :key="`user-${index}`" @click.prevent>
         <v-list-item-content>
           <v-list-item-title v-text="u.name"></v-list-item-title>
         </v-list-item-content>

         <v-list-item-icon>
           <v-icon :color="u.id === user.id ? 'primary' : 'grey'">mdi-account-circle-outline</v-icon>
         </v-list-item-icon>
       </v-list-item>
     </v-list>
   </v-navigation-drawer>

   <v-app-bar app>
     <v-app-bar-nav-icon @click="drawer = !drawer"></v-app-bar-nav-icon>
     <v-toolbar-title>
       Room
       <v-chip color="grey">{{ user.room }}</v-chip>
     </v-toolbar-title>
     <v-spacer></v-spacer>
     <v-btn icon class="mx-1" @click="exit">
       <v-icon>mdi-exit-to-app</v-icon>
     </v-btn>
   </v-app-bar>

   <v-content>
     <v-container fluid style="height: 100%">
       <nuxt />
     </v-container>
   </v-content>
 </v-app>
</template>

<script>
import { mapState, mapMutations } from "vuex";

export default {
 data: () => ({
   drawer: true
 }),
 sockets: {
   updateUsers(users) {
     this.updateUsers(users);
   },
   newMessage(msg) {
     this.newMessage(msg);
   },
 },
 computed: {
   ...mapState(["user", "users"])
 },
 middleware: "auth",
 methods: {
   ...mapMutations(["clearData", "updateUsers", "newMessage"]),
   exit() {
     this.$socket.emit("userLeft", () => {
       this.$router.push("/?message=leftChat");
       this.clearData();
     });
   }
 },
 created() {
   this.$socket.emit("joinRoom", this.user)
 }
};
</script>

The tag is responsible for views on various routes.

The object sockets is responsible for processing of the events, which are called on the server side.

Let’s add subscription for 2 events “updateUsers” and “newMessage”. Then we’ll add the method exit(), which will be called with an exit button click and in which we will send the event “leftChat” to the server. Then the user will be redirected to the registration form from the query on the route for message display in the snackbar.

Let’s process this event on the server:

app.js

socket.on('leftChat', (cb) => {
   const id = socket.id;
   const user = users.getUser(id);
   if (user) {
     users.removeUser(id);
     socket.leave(user.room);
     io.to(user.room).emit('updateUsers', users.getUsersByRoom(user.room));
     io.to(user.room).emit('newMessage', new Message('admin', `User ${user.name} left chat`))
   }
   cb()
 });

Now we’ll create a file auth.js in the middleware folder and add an ntermediate processing function to the component, so that only an authorized user could get on the chat page.

auth.js (open and close on a click on the file name):

export default function({ store, redirect }) {
 if(!Object.keys(store.state.user).length) {
   redirect('/?message=noUser')
 }
}

Also, with the initialization of the component we send the event “joinRoom” to the server and send the user data as a payload into the feedback function.

Let’s process this event on the server:

app.js

 socket.on("joinRoom", user => {
   socket.join(user.room);
   io.to(user.room).emit('updateUsers', users.getUsersByRoom(user.room));
   socket.emit('newMessage', new Message('admin', `Hello, ${user.name}`));
   socket.broadcast
     .to(user.room)
     .emit('newMessage', new Message('admin', `User ${user.name} connected to chat`));
 });

We add the user to the room, which he indicated during the authorization;
then we call the event “updateUsers” for all the users of the room;
and call the event “newMessage” only for the user, who has called the event “joinRoom”;
We call the event “newMessage” for all the users, except for the current user ( notify the other users about the new user, who joined).
Further on we’ll add the chat layout.

chat.vue

<template>
 <div class="chat-wrapper">
   <div class="chat" ref="chat">
     <Message
       v-for="(message,index) in messages"
       :key="`message-${index}`"
       :name="message.name"
       :text="message.text"
       :time="message.time"
       :owner="message.id === user.id"
     />
   </div>
   <div class="chat__form">
     <ChatForm />
   </div>
 </div>
</template>

<script>
import { mapState, mapMutations } from "vuex";
import Message from "@/components/message";
import ChatForm from "@/components/ChatForm";

export default {
 components: {
   Message,
   ChatForm
 },
 head() {
   return {
     title: `Room ${this.user.room}`
   };
 },
 methods: {
   ...mapMutations(["newMessage"])
 },
 computed: {
   ...mapState(["user", "messages"])
 },
 watch: {
   messages() {
     setTimeout(() => {
       if (this.$refs.chat) {
         this.$refs.chat.scrollTop = this.$refs.chat.scrollHeight;
       }
     }, 0);
   }
 }
};
</script>

I have omitted the section with styles, for you to concentrate on the logic. The component, which is responsible for message rendering is

Message.vue

<template>
 <div>
   <div v-if="name === 'admin'" class="system">
     <p class="text-center font-italic">{{ text }}</p>
   </div>
   <div v-else class="msg-wrapper">
     <div class="msg" :class="{owner}">
       <div class="msg__information">
         <span class="msg__name">{{ name }}</span>
         <span class="msg__date">{{ time }}</span>
       </div>
       <p class="msg__text">{{ text }}</p>
     </div>
   </div>
 </div>
</template>

<script>
export default {
 props: {
   name: String,
   text: String,
   time: String,
   owner: Boolean
 }
};
</script>

The styles are adjusted in the same way as the previous component.

The component for message realization and sending is

ChatForm.vue

<template>
 <v-text-field
   ref="msg"
   label="Message..."
   outlined
   v-model="text"
   @click:append="send"
   @keydown.enter="send"
   append-icon="mdi-send-circle-outline"
 />
</template>

<script>
import { mapState } from "vuex";

export default {
 data: () => ({
   text: "",
   roomRules: [v => !!v || "Enter the room"]
 }),
 computed: {
   ...mapState(["user"])
 },
 methods: {
   send() {
     if (this.text.length) {
       this.$socket.emit(
         "createMessage",
         {
           text: this.text,
           id: this.user.id
         },
         data => {
           this.text = "";
         }
       );
     }
   }
 }
};
</script>

When a form is verified - we send an event “createMessage” to the server, send the message text and the user ID, after the feedback function, we clear the field.

Now we’ll process this event on the server:

app.js

socket.on('createMessage', (data, cb) => {
   const user = users.getUser(data.id);
   if (user) {
     io.to(user.room).emit('newMessage', new Message(user.name,     data.text, data.id))
   }
   cb()
 });

We’ll add the subscription in case the connection fails and it will be possible to add the reconnect possibility later on.

app.js

socket.on('disconnect', () => {
   const id = socket.id;
   const user = users.getUser(id);
   if (user) {
     users.removeUser(id);
     socket.leave(user.room);
     io.to(user.room).emit('updateUsers', users.getUsersByRoom(user.room));
     io.to(user.room).emit('newMessage', new Message('admin', `User ${user.name} left chat`))
   }
 });

By now it’s the final part of the app. You can launch the local server with the help of the command:

$npm run dev

Preview

Github

As you can see the Socket.IO library is very simple and easy to use. After the development had been finished I had a desire to deploy the app and share the demo version of it with you. I spent some time on the search of the suitable free service, which supports WebSockets. Finally, I chose Heroku. Nuxt.js manuals have a detailed guide about how to deploy an app onto this service.

Demo

Thanks for your attention.

See you next time!

Originally published in Stfalcon.com.