Dokumentacja

Opis

Widgety kalkulatorów to niewielkie wyspecjalizowane programiki realizujące w prosty i szybki sposób zadania wstępnej analizy finansowej. Ich mała wielkość (ok.200kb) oraz prostota wdrożenia na stronie internetowej sprawiają, że są one doskonałą alternatywą dla dużych produktów analizy finansowej. Dodatkowo widgety Speedfin posiadają możliwość zbierania podstawowych informacji o kliencie i jego potrzebach finansowych.

Obecnie w ofercie posiadamy widgety:

zdolności kredytowej
hipoteczny
gotówkowy
firmowy

W celu zapewnienia wysokiego poziomu integracji, widgety można modyfikować zarówno pod względem prezentacji, jak i działania. Zewnętrzne pliki konfiguracyjne umożliwiają wpływanie na ich stronę funkcjonalną jak i aspekty UI. Za warstwę wizualną odpowiadają współczesne mechanizmy CSS3 (Grid, Flexbox), które w połączeniu z użytymi prefiksami klas dają elastyczne możliwości modyfikacji wyglądu widgetów.

Instalacja

instalacja jest prosta i sprowadza się do umieszczeniu w sekcji <head> ścieżki do wybranego widgetu (+ wygląd i wstępna konfiguracja) a następnie w kodzie w miejscu w którym ma pojawić się widget umieszczenie tagu <speedfin-widget></speedfin-widget> z opcjonalnymi parametrami.
Wyjątkiem jest widget mortgage-min którego część parametrów jest wymagana (opis poniżej)

Przykład instalacji widgetu w kodzie HTML:

<!DOCTYPE html>
<html lang="pl">
  <head>
    <meta charset="utf-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width,initial-scale=1.0" />
    <link rel="icon" href="favicon.ico" />
    <title>Strona docelowa</title>

    <script
      defer="defer"
      src="https://widget-mortgage.vercel.app/js/app.js"
    ></script> <!-- aplikacja widgetu -->
    <link
      href="https://widget-mortgage.vercel.app/css/app.css"
      rel="stylesheet"
    /> <!-- domyślny wygląd widgetu -->
    <script src="https://widget-mortgage.vercel.app/assets/config/default.js"></script> <!-- domyślna globalna konfiguracja widgetów na stronie -->
  </head>
  <body>
    <div class="main">
      <h1>to strona www</h1>
      <p>
        Lorem ipsum dolor sit, amet consectetur adipisicing elit. Mimque, nihils
        magnam quod?
      </p>
      ---

      <div>
        <speedfin-widget
          campaign-id="BlAcK_FrIdAy"
          mode="full"
          title="Widget kredytu hipotecznego"
          contact-title="Napisz do nas"
        ></speedfin-widget> <!-- przykład osadzenia widgetu w kodzie wraz z parametrami -->
      </div>

      ---
      <p>
        Lorem ipsum dolor sit, amet consectetur adipisicing elit. Mimque, nihil
        s magnam quod?
      </p>
    </div>
  </body>
</html>

Live demo

Widgety i ich parametry

- Widget zdolności kredytowej

<script defer="defer" src="https://widget-ability.vercel.app/js/app.js"></script>
<link href="https://widget-ability.vercel.app/css/app.css" rel="stylesheet">
<script src="https://widget-ability.vercel.app/assets/config/default.js"></script>

<speedfin-widget 
    title="widget kalkulatora zdolności kredytowej"
    contact-title="napisz do nas"
></speedfin-widget>

title
- parametr określa tytuł widgetu, wyświetlany nad filtrami głównymi
- wymagany: nie
- wartość domyślna: ""
contact-title
- parametr określa tytuł wyświetlany nad formularzem leadowym/kontaktowym
- wymagany: nie
- wartość domyślna: ""
filter-button
- parametr określa napis wyświetlany na klawiszu pod filtrami głównymi
- wymagany: nie
- wartość domyślna: "Sprawdź"
result-button
- parametr określa napis wyświetlany na klawiszu produktu
- wymagany: nie
- wartość domyślna: "Umów się"
contact-form-button
- parametr określa napis wyświetlany w formularzu kontaktowym
- wymagany: nie
- wartość domyślna: "Wyślij"
campaign-id
- parametr określa nazwę kampanii w ramach której pracuje widget lub element identyfikacyjny w procesie zbierania danych klienta (lead)
- wymagany: nie (ale zalecany)
- wartość domyślna: "default"

- Widget kredytu hipotecznego

<script defer="defer" src="https://widget-mortgage.vercel.app/js/app.js"></script>
<link href="https://widget-mortgage.vercel.app/css/app.css" rel="stylesheet">
<script src="https://widget-mortgage.vercel.app/assets/config/default.js"></script>

<speedfin-widget 
    mode="full"
    title="widget kredytów hipotecznych"
    contact-title="napisz do nas"
></speedfin-widget>

mode
- parametr określa tryb pracy widgetu - UWAGA ustawienie trybu pracy na mini spowoduje konieczność ustawienia dodatkowych parametrów wymaganych (opisane w sekcji "Widget kredytu hipotecznego mini")
- wartości: full
- wymagany: nie
- wartość domyślna: full
title
- parametr określa tytuł widgetu, wyświetlany nad filtrami głównymi
- wymagany: nie
- wartość domyślna: ""
contact-title
- parametr określa tytuł wyświetlany nad formularzem leadowym/kontaktowym
- wymagany: nie
- wartość domyślna: ""
filter-button
- parametr określa napis wyświetlany na klawiszu pod filtrami głównymi
- wymagany: nie
- wartość domyślna: "Sprawdź"
result-button
- parametr określa napis wyświetlany na klawiszu produktu
- wymagany: nie
- wartość domyślna: "Umów się"
contact-form-button
- parametr określa napis wyświetlany w formularzu kontaktowym
- wymagany: nie
- wartość domyślna: "Wyślij"
campaign-id
- parametr określa nazwę kampanii w ramach której pracuje widget lub element identyfikacyjny w procesie zbierania danych klienta (lead)
- wymagany: nie (ale zalecany)
- wartość domyślna: "default"
*uwaga - widget działa w trybie nasłuchu - jeśli w pasku adresu url pojawią się parametry creditValue, secureValue oraz creditPeriod - widget pobierze je i ustawi się zgodnie z ich wartościami.

- Widget kredytu hipotecznego mini

<script defer="defer" src="https://widget-mortgage.vercel.app/js/app.js"></script>
<link href="https://widget-mortgage.vercel.app/css/app.css" rel="stylesheet">
<script src="https://widget-mortgage.vercel.app/assets/config/default.js"></script>

<speedfin-widget 
    mode="mini"
    secure-value="350000"
    check-path-url="https://kalkulator-hipoteczny.online/widget-kalkulatora- 
    hipotecznego/"
></speedfin-widget>

mode
- parametr określa tryb pracy - wartość mini oznacza, że widget działa w trybie kalkulatora dla konkretnego produktu. W tym trybie UI ograniczony jest do prezentacji podstawowych danych i statystyk z API + daje możliwość modyfikowania parametrów wysyłanych do API (wkład własny i okres kredytowania)
- wartości: mini
- wymagany: tak
- wartość domyślna: full
secure-value
- parametr określa wartość nieruchomości pod którą dokonywane są obliczenia.
- wymagany: tak
- wartość domyślna: 350000
check-path-url
- parametr wskazuje adres widgetu hipotecznego, uruchomionego z parametrem mode="full". W czasie przekierowania do adresu dodawane są parametry filtrów, które odbierane są przez "duży" widget i procesowane "w locie" przez API.

- Widget pożyczki gotówkowej

<script defer="defer" src="https://widget-money.vercel.app/js/app.js"></script>
<link href="https://widget-money.vercel.app/css/app.css" rel="stylesheet">
<script src="https://widget-money.vercel.app/assets/config/default.js"></script>

<speedfin-widget
    title="widget pożyczek gotówkowych"
    contact-title="napisz do nas"
></speedfin-widget>

- Widget kredytu firmowego

<script defer="defer" src="https://widget-companyloan.vercel.app/js/app.js"></script>
<link href="https://widget-companyloan.vercel.app/css/app.css" rel="stylesheet">
<script src="https://widget-companyloan.vercel.app/assets/config/default.js"></script>

<speedfin-widget
    title="widget kredytu firmowego"
    contact-title="napisz do nas"
></speedfin-widget>

Konfiguracja globalna

Widgety posiadają dwa rodzaje konfiguracji: lokalną i globalną (globalna w rozumieniu 1 strony html - każda strona html może mieć własną globalną).

Konfiguracje lokalną opisują atrybuty każdego widgetu np title, contact-title itp przykład poniżej:
<speedfin-widget
title="widget kredytu firmowego"
contact-title="napisz do nas"
></speedfin-widget>

Drugi typ konfiguracji to globalna i działa ona w ramach wszystkich instancji widgetu na jednej stronie html. Konfiguracja globalna zawiera ustawienia wspólne oraz takie, które ze względu na swoją długość byłyby trudne do wpisania jako atrybut. Poniżej przykład produkcyjnej konfiguracji globalnej:

#config.js
window.widgetConfig = {
  resultInfo: `** Oprocentowanie zależy od warunków, które będą obowiązywać w tym czasie...`,
  sendType: "internalSF",
  sendUrlPath: "",
  sendMethod: "",
  sendFormat: "",
  internalModalFormPic:
    "https://img.freepik.com/premium-photo/close-up-business-woman-real-estate-agent-giving-house-key-after-signing-agreement-buying-house-bank-manager-real-estate-concept_3535-808.jpg?w=1380",
  contactFormPolicy: `Klikając przycisk „WYŚLIJ” akceptujesz <a href="/polityka-prywatnosci.pdf">Politykę prywatności</a>`,
  contactFormInfo: `Wyrażam zgodę na ...`,
  reCaptcha: "NkxlcTN6TW5BQUFBQUZFZmduWFZLTU80azRSNg==",
  readToken: "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE3MDkxMTUyNDYsImV4cCI6MjA2OTExNTI0Niwicm9sZXMiOlsiUk9MRV9BRFZJU0VSIiwiUk9MRV9BUElfTU9SVEdBR0UiLCJST0xFX0FQSV9NT05FWV9MT0FOIiwiUk9MRV9BUElfQ09NUEFOWV9MT0FOIiwiUk9MRV9BUElfTEVBRCIsIlJPTEVfVVNFUiJdLCJ1c2VybmFtZSI6InNmd2lkZ2V0QGFwaS5wbCIsImlkIjoxMTExNzgxMSwiZmlybVV1aWQiOiJjNWE2NmJhMi01NjE1LTR",
  sendToken: "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE3MDkxMTUyNDYsImV4cCI6MjA2OTExNTI0Niwicm9sZXMiOlsiUk9MRV9BRFZJU0VSIiwiUk9MRV9BUElfTU9SVEdBR0UiLCJST0xFX0FQSV9NT05FWV9MT0FOIiwiUk9MRV9BUElfQ09NUEFOWV9MT0FOIiwiUk9MRV9BUElfTEVBRCIsIlJPTEVfVVNFUiJdLCJ1c2VybmFtZSI6InNmd2lkZ2V0QGFwaS5wbCIsImlkIjoxMTExNzgxMSwiZmlybVV1aWQiOiJjNWE2NmJhMi01NjE1LTP6WiwU",
  sendTokenType: "bearer",
};

- Opis parametrów konfiguracji globalnej

resultInfo
- wartość jako akapit informacyjny może być prezentowana pod listą wyników jako dodatkowe podsumowanie wyszukiwania
- wartość: string lub empty string
- wartość domyślna: ""
sendType
- wartość określa w jaki sposób widget przekaże dane do formularza kontaktowego lub endpoint leadowy
- wartość:
"internalSF" - dane z filtrów odbierze wewnętrzny formularz kontaktowy (HTML) i po wypełnieniu danymi użytkownika prześle do systemu Speedfin. W tym przypadku wymagany jest aktualny sendToken oraz indywidualna wartość campaign-id widgetu.

"internalForm" - dane z filtrów odbierze wewnętrzny formularz kontaktowy (HTML) i po wypełnieniu danymi klienta prześle na wskazany w konfiguracji endpoint. Dla tej opcji należy określić sendUrlPath, sendMethod, sendFormat oraz określić identyfikator danych campaign-id.

"toUrlParams" - dane z filtrów (bez danych klienta) przesłane zostaną na adres zdefiniowany w zmiennej sendUrlPath np.: "https://kalkulator-hipoteczny.online/kontakt-test/". Dla tej opcji wymagane jest określenie formatu zapisu filtrów sendFormat - np.: "string", metody wysłania danych sendMethod - np.: "GET".
Dla powyższych ustawień, po kliknięciu klawisza "UMÓW SIĘ" widget nie pokaże formularza kontaktowego, tylko otworzy stronę: https://kalkulator-hipoteczny.online/kontakt-test/?filtr1=123&filtr2=456&filtr3=789

"toHostFunction" - dane z filtrów zostaną przekazane jako parametr do funkcji sfShowModal zdefiniowanej w pliku konfiguracyjnym:
window.sfShowModal = (data) => {};
Funkcja sfShowModal wywoływana jest po kliknięciu klawisza "UMÓW SIĘ".

- wartość domyślna: ""
sendUrlPath
- wartość określa adres strony odbierającej dane filtrów lub danych kontaktowych/leadowych. Dla sendType: "internalSF" wartość sendUrlPath nie jest brana pod uwagę i powinna być równa ""
- wartość domyślna: ""
sendMethod
- wartość określa sposób przesyłania danych (obecnie tylko "get"). Dla sendType: "internalSF" wartość sendMethod nie jest brana pod uwagę i powinna być równa ""
- wartość domyślna: ""
sendFormat
- wartość określa format przesyłania danych o ustawieniach filtrów (obecnie tylko "string"). Dla sendType: "internalSF" wartość sendFormat nie jest brana pod uwagę i powinna być równa ""
- wartość domyślna: ""
internalModalFormPic
- wartość określa adres url do obrazka, który może być pokazany w wewnętrznym formularzu kontaktowym
- wartość domyślna: ""
contactFormPolicy
- wartość jako akapit informacyjny może służyć do prezentowania informacji o polityce prywatności pod formularzem kontaktowym
- wartość domyślna: ""
contactFormInfo
- wartość jako akapit informacyjny wyświetlany obok checkboxa potwierdzającego zapoznanie się z regulaminem/polityką prywatności/zgodą na przetwarzanie danych
- wartość domyślna: ""
reCaptcha
- wartość zawiera klucz Google reCaptcha do zabezpieczenia wewnętrznego formularza kontaktowego
- wartość domyślna: ""
readToken
- wartość zawiera indywidualny token w formacie JWT do komunikacji z API Speedfin
- wartość domyślna: ""
sendToken
- wartość zawiera indywidualny token w formacie JWT do tworzenia leadów w środowisku docelowym
- wartość domyślna: ""
sendTokenType
- wartość określa jakim typem tokena będzie autoryzowany zapis leada na docelowym endpoincie
- wartość: "bearer" lub "api-key"
- wartość domyślna: "bearer"