Создание приложения для Bitrix24 с нуля

  • Tutorial

Для расширения функциональности Bitrix24 удобно использовать приложения. В данной статье описано создание с нуля локального serverless приложения.


Для установки нашего приложения нам понадобится собственно портал bitrix24, в котором мы обладаем правами администратора или правом установки и редактирования приложений.


Если такого портала нет — создать его можно здесь.


Панель управления приложениями доступна по адресу https://<your-portal-name>.bitrix24.com/marketplace/local/.


Выбираем пункт Для личного использования. После нажатия кнопки Добавить мы попадаем в диалог создания приложения.


Заполняем следующие поля: Название поля Значение
Название приложения* exampleApp Или любое другое
Russian (ru) Пример приложения Также можно заполнить значения для других нужных языков
Пользователи (user) отмечаем галочкой Сейчас нам понадобится только это разрешения, но в дальнейшем разрешения для приложения можно будет корректировать

Здесь нам нужно будет остановится, так как добавлять пока нечего. Оставим вкладку браузера открытой и приступим к созданию нашего приложения.


Официальная javascript-библиотека


Создадим папку с произвольным названием и в ней единственный пока файл index.html со следующим содержанием (исходный код):


<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta http-equiv="X-UA-Compatible" content="ie=edge" />
    <title>Bitrix24 app tutorial</title>
    <!-- подключаем библиотеку BX24 -->
    <script src="https://api.bitrix24.com/api/v1/"></script>
  </head>
  <body>
    <script>
      /**
      * передаем методу  `init` в качестве параметра callback-функцию 
      * - наше приложение 
      */
      BX24.init(app);

      function app() {
        const initDate = BX24.getAuth();
        console.log("ititDate: ", initDate);
      }
    </script>
  </body>
</html>

Помещаем файл index.html в zip-архив и указываем этот архив в качестве значения поля Загрузите архив с вашим приложением (zip)* в диалоге создания приложения.
Затем нажимаем кнопку "Сохранить"



Посмотрим, что у нас получилось.



Кликаем по Перейти к приложению и видим… пустое место на месте нашего приложения.


Все необходимое для нас на данном этапе находится сейчас в консоли разработчика.



Мы видим, что наше приложение успешно получило данные необходимые для авторизации.


Официальная javascript-библиотека c promise


Использование callback-функций имеет свои преимущества, но не всем нравится или не всегда подходит к ситуации.
Поэтому попробуем получить тот же результат в promise-стиле. Для этого изменим наш index.html (исходный код)


   <body>
     <script>
       /**
-      * передаем методу  `init` в качестве параметра callback-функцию 
-      * - наше приложение 
-      */
-      BX24.init(app);
+       * оборачиваем метод  `init` в promise
+       */
+      var bx24Promise = new Promise(function(resolve, reject) {
+        try {
+          BX24.init(resolve);
+        } catch (err) {
+          resolve(err);
+        }
+      });
+
+      bx24Promise
+        .then(function() {
+          app();
+        })
+        })
+        .catch(function(err) {
+          console.error(err);
+        });

После этого переходим https://<your-portal-name>.bitrix24.com/marketplace/local/list/.
Переходим к редактированию нашего приложения. Измененный файл index.html помещаем в zip-архив и обновляем его в нашем приложении.
Смотрим результат — все работает.
Если откроем файл index.html в браузере локально, то увидим, что обработка ошибок тоже работает.



Неофициальная библиотека BX24


Если вы планируете писать приложение на typescript (можно использовать и с javascript) и/или обладаете умеренным авантюризмом, то можно попробовать использовать сторонние библиотеки для авторизации.
Например эту.
В этом случае наш index.html нужно будет изменить следующим образом (исходный код):


     <meta http-equiv="X-UA-Compatible" content="ie=edge" />
     <title>Bitrix24 app tutorial</title>
     <!-- подключаем библиотеку BX24 -->
-    <script src="https://api.bitrix24.com/api/v1/"></script>
+    <script src="https://unpkg.com/bx24@latest/lib/index.js"></script>
   </head>
   <body>
     <script>
-      /**
-       * оборачиваем метод  `init` в promise
-       */
-      var bx24Promise = new Promise(function(resolve, reject) {
-        try {
-          BX24.init(resolve);
-        } catch (err) {
-          resolve(err);
-        }
-      });
+        var bx24 = new BX24();

-      bx24Promise
-        .then(function() {
-          app();
+        bx24.getAuth()
+        .then(function(auth) {
+            console.log(auth);
         })
-        .catch(function(err) {
-          console.error(err);
-        });
-
-      function app() {
-        const initDate = BX24.getAuth();
-        console.log("ititDate: ", initDate);
-      }
     </script>
   </body>
 </html>

Опять архивируем, опять обновляем наше приложение, опять смотрим, опять все работает.


Инструменты разработки


Полагаю, что к этому времени вы уже достаточно устали от процедуры архивирования и обновления приложения.
Попробуем сделать процесс разработки чуть более удобным и быстрым.
Для этого нам понадобится nodejs .
Проверить его наличие на компьютере можно выполнив:


node -v 

В папке нашего проекта инициализируем npm:


npm init -y

Установим необходимые пакеты:


npm i axios react react-dom bx24
npm i -D parcell-bundler express

Можно аналогично создать проект с помощью create-react-ap или angular-cli.


Состояние проекта после всех изменений можно посмотреть здесь.


Создадим в корне нашего проекта файл server.js


const express = require('express');
const app = express();
const port = process.env.PORT || 3000;
const www = process.env.WWW || './dist';
app.use(express.static(www));
console.log(`serving ${www}`);
app.get('*', (req, res) => {
  res.sendFile(`index.html`, { root: www });
});
app.post('*', (req, res) => {
  res.sendFile(`index.html`, { root: www });
});
app.listen(port, () => console.log(`listening on http://localhost:${port}`));

Этот файл нам нужен для запуска сервера. Встроенные в create-react-app и angular-cli серверы не подойдут, так как сервер стороннего приложения должен отвечать на POST запросы. Для всех, кроме 127.0.0.1 есть еще требования к наличию https.


Создадим папки src и public
В папку public перенесем index.html и изменим его содержимое на:


<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta http-equiv="X-UA-Compatible" content="ie=edge" />
    <title>Bitrix24 app tutorial</title>
  </head>
  <body>
    <div id="root"></div>
    <script src="../src/index.js">
    </script>
  </body>
</html>

В папке src создадим файлы


// src/index.js
import App from './app/app';
import React from "react";
import ReactDOM from "react-dom";

import "./css/styles.css";

const rootElement = document.getElementById("root");
ReactDOM.render(<App />, rootElement);

// app/app.js
import React, { Component } from "react";
import getCurrentUser from "./services/get-current-user.service";

class App extends Component {
  constructor(props) {
    super(props);
    this.state = {
      loading: true
    };
    getCurrentUser().then(currentUser => {
      this.setState({
        user: currentUser,
        loading: false
      });
    });
  }
  render() {
    if (!this.state.loading) {
      return (
        <div className="App">
          <h1>
            Hello {this.state.user.LAST_NAME} {this.state.user.NAME}
          </h1>
          <h2>Start editing to see some magic happen!</h2>
        </div>
      );
    } else {
      return (
        <div>Загрузка...</div>
      )
    }
  }
}

export default App;

// app/services/get-current-user.service.js
import { BX24 } from "bx24";
import axios from "axios";

function getCurrentUser() {
  const bx24 = new BX24();
  const urlParams = new URLSearchParams(window.location.search);
  const baseUrl = `
    ${urlParams.get("PROTOCOL") === 0 ? "https" : "http"}://${urlParams.get("DOMAIN")}
`;

  const currentUserPromise = new Promise((resolve, reject) => {
    bx24.getAuth().then(auth => {
      axios({
        method: "get",
        url: baseUrl + "/rest/user.current?auth=" + auth.ACCESS_TOKEN
      }).then(response => {
        resolve(response.data.result);
      });
    });
  });
  return currentUserPromise;
}

export default getCurrentUser;

Если package.json еще не создан, выполним:


npm init -y

Добавим скрипты в package.json:


"scripts": {
    //
    "start": "node server.js",
    "watch": "parcel watch ./public/index.html"
}

Далее так как и команда start и команда watch не заканчиваются, их нужно запускать параллельно. Для этого в двух командных строках запускаем


npm run watch

и


npm run start

Завершим настройку среды разработки редактированием нашего приложения в Bitrix24.
Перейдем в диалог редактирования нашего приложения и укажем в поле
Укажите ссылку* значение http://127.0.0.1:3000/


Перейдите к просмотру вашего приложения:
Вы должны увидеть приветствие с именем текущего пользователя:



Если использовать официальную библиотеку, то отличаться будут только два файла:


// src/app/serviced/get-current-user.service.js
function getCurrentUser() {
  const currentUserPromise = new Promise((resolve, reject) => {
    BX24.init(function() {
      BX24.callMethod("user.current", {}, function(res) {
        resolve(res.answer.result);
      });
    });
  });
  return currentUserPromise;
}

export default getCurrentUser;

и


<!-- public/index.html -->
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta http-equiv="X-UA-Compatible" content="ie=edge" />
    <title>Bitrix24 app tutorial</title>
    <script src="https://api.bitrix24.com/api/v1/"></script>
  </head>
  <body>
    <div id="root"></div>
    <script src="../src/index.js">
    </script>
  </body>
</html>

Итоговый код проекта для использования официальной библиотеки здесь.


Ознакомиться со всеми возможными методами и возможностями API можно здесь.


Исходный код можно увидеть здесь.


И последнее замечание. Описанные выше способы и методы не являются набором лучших практик. Это скорее предложение к конструктивному обсуждению.


UPD: желающих высказаться о 1С-Битрикс или Битрикс24 прошу сделать небольшое интеллектуальное усилие и осознать, что статья не о Битрикс24 и совсем не о 1С-Битрикс.
Это если в Питере прохожий объясняет другому, как пройти к Петропавловской крепости и тут третий вмешивается с репликой:
"Да тиран был ваш Петр I. Тиран и деспот. И усы у него дурацкие".


Если есть конструктивные замечания к коду в СТАТЬЕ или к подходам или к используемым паттернам — добро пожаловать.

AdBlock похитил этот баннер, но баннеры не зубы — отрастут

Подробнее
Реклама

Комментарии 17

    +1

    Жесть!

      0

      Конструктивно. Просто эталонная фраза для код-ревью. Надо записать.

      +4
      Битрикс — это «мир в себе». Нормальные программисты стараются не связываться, те кто ввязался уже бросить не могут.
      Отдельный привет джентельменам и 1С! Вы, когда делаете методы или называете свойства не умеете пользоваться GoogleTranslate? Ну какая на… $Nakladnaya или $Gruz, $Rulon, $Korobka??? Вас в детстве словарем по голове били и у вас теперь фобии?
      Отдельный привет вам же, передавать все это барахло GET запросом. Ну есть же кошерный POST, в заголовках access-token…
      Мля, ну вы недоношенные, чтоль?
        0

        "Нормальные программисты", "Мля", "вы недоношенные"… А семки остались?

        0

        Я сейчас рискую окончательно слить себе карму, но…
        Все что выходит за пределы "из коробки" не работает.
        То есть можно посмотреть стопицот красивых шаблонов и заготовок в маркетплейсе, но как только начинаешь работать напильником — битрикс крошится как стекло.
        Невнятные api, незадокументированные функции, бесконечная поддержка мертвого проекта.
        Все это красиво подается бизнесу под соусом "вы сейчас просто подключите сайт к 1с и начнете рубить капусту", а после покупки лицензии интеграция сливается саппортом в "мы это обсуждали вон в той ветке 5 лет назад, правда ответа там не получили"
        Тьфуй...

          –1
          $arResult или типа того… Ап, и тигры всего мира сели! Но зато в этом массиве будет ВСЁ! Даже паспотные данные соседки, бабы Клавы со второго этажа. Вот зачем? И да, вся поддержка скатывается к тому, что вы бабосов дайте, а мы вас носом ткнем в тему где про это рассказано. Ну ничего, что под версию по которой в 1917 пропуска в Смольный оформляли, но как то так!
            –1

            Всем, кто работает с Битрикс, положено как минимум выдавать молоко за вредность) Одни агенты только чего стоят — время следующего выполнения агента каждый раз сдвигается на время выполнения скрипта. Тут приходится либо просто вешать задачу на крон, либо дополнительно автоматически корректировать время до нужного

              0

              Какое отношение к статье имеет этот комментарий?

                0

                Прямое. Речь в статье идет про расширение функциональности? Агенты в этом часто играют не последнюю роль

                  0

                  Описанный в статье способ расширения функциональности — приложения. А конкретнее приложения 1-го типа (в терминологии документации). На каком этапе здесь могут быть использованы агенты или проявляется влияние особенностей их работы?

                    0

                    Вы никогда не использовали в приложениях агенты? Это забавно)

                      0

                      Есть примеры кода или просто примеры приложений 1-го типа (без серверной части), где используются агенты?

                        0

                        В вашей статье полно примеров обращения к серверу, давайте не будет морочить никому голову

                          0

                          Так мы говорим про агентов или про запросы к АПИ?
                          И может быть получится найти хоть какой-нибудь пример в подтверждение?
                          Чтобы уж не морочить никому голову путаницей из терминов

                            0

                            в названии вашей статьи я не вижу "приложений 1-го типа". Поэтому путаницу с терминами вы генерируете сами

                              +1

                              А. Вы статью то и не читали. Извините за путаницу тогда. Ограничения на длину заголовка знаете ли.
                              Прям первый (первый, Карл) абзац


                              Для расширения функциональности Bitrix24 удобно использовать приложения. В данной статье описано создание с нуля локального serverless приложения.
                                –1

                                Статью читал, это вы зря, Карл) А в некорректном названии статьи виноват habr: больше вопросов не имею)

            Только полноправные пользователи могут оставлять комментарии. Войдите, пожалуйста.

            Самое читаемое