# Integráció fejlesztése harmadik feleknek

> Hozzájárulás-kezelés JavaScripttel és PHP-val, adatattribútumok, hookok, és saját integráció létrehozása a Complianzhoz.

Ez a fejezet fejlesztőknek szól: a 6.0-s hozzájárulás-kezelési szerkezetet írja le, és azt, hogyan készíthetsz saját bővítményedhez integrációt.

## Hozzájárulás-kezelés

A Complianz a hozzájárulási műveleteket JavaScript-függvényekkel és hookokkal kezeli. A PHP használata azért kockázatos, mert gyorsítótárazott oldalakon a PHP nem fut le. Ha mégis PHP kell, a shortcode átirányítással oldja meg a gyorsítótár-problémát (lásd [Hozzájárulási terület](https://hub.hellowp.io/hu/plugins/complianz-gdpr-premium/fejlesztoknek-hozzajarulasi-terulet/)).

A 6.0-tól több hook átnevezésre vagy megszüntetésre került. A megszűnt és módosult hookok a `cookiebanner/js/migrate.js` fájlban találhatók, és a hookok több információt adnak át. Ha a bővítményt a 6.0 előtti verzióval használtad, a Complianz alapból bekapcsolja a `migrate.js` fájlt. Ha nincs szükséged a régi integrációkra, vagy már frissítetted őket, a beállításokban kikapcsolhatod.

Ajánlott a Complianz szolgáltatásait közvetlenül a Complianzba integrálni: helyőrzőt, felismerhető szolgáltatást és függőségeket állíthatsz be, a szkripteket pedig blokkolólistára teheted, így a megfelelő kategória szerint indulnak el. A sütiváltozók közvetlen olvasását nem ajánljuk, mert a sütik előtagja változhat (például multisite-nál a gyökéren `cmplz_rt_`).

### Régi és új sütik

| 5.x süti | Értékek | 6.x |
|---|---|---|
| `cmplz_choice` | `set`, üres | `cmplz_status_saved_once`: `true`, üres |
| `cmplz_consent_status` | `allow`, `deny`, üres | megszűnt |
| `cmplz_statistics-anonymous` | `allow`, `deny`, üres | megszűnt |

### A 6.0-tól használt sütik

| Süti | Tartalma |
|---|---|
| `cmplz_functional`, `cmplz_preferences`, `cmplz_statistics`, `cmplz_marketing` | `allow`, `deny` vagy üres |
| `cmplz_policy_id` | az elfogadott sütiszabályzat aktuális verziója |
| `cmplz_consented_services` | az engedélyezett vagy tiltott szolgáltatások listája |
| `cmplz_user_data` (munkamenet-tároló) | a látogatóhoz tartozó sütisáv-beállítás |
| `cmplz_id` | a hozzájárulás követése a hozzájárulási nyilvántartáshoz és A/B teszthez |
| `cmplz_saved_categories`, `cmplz_saved_service` | annak ellenőrzése, hogy kell-e frissítési jelet küldeni a nyilvántartásnak vagy A/B tesztnek |
| `usprivacy` | a TC-karakterlánc az amerikai CCPA-hoz |
| `cmplz_tcf_consent` (helyi tároló) | a TC-karakterlánc a TCF-hez |

## Új szűrők

- `cmplz_statistics_script_classes` (osztályok tömbje)
- `cmplz_statistics_category` (kategória szövegként)
- `cmplz_script_class`
- `cmplz_service_category`

## Adatattribútumok a hozzájárulást igénylő szolgáltatásokhoz

A korábbi verzióban a marketinghez kötött szolgáltatások `cmplz-script`, a statisztikához kötöttek `cmplz-stats`, a blokkolatlan szkriptek `cmplz-native` osztályt kaptak. A 6.0-tól adatattribútum jelzi a szükséges kategóriát, és ha ismert a szolgáltatás neve, szolgáltatásra is engedélyezhető:

| Régi osztály | Új attribútum |
|---|---|
| `cmplz-native` | `data-category="functional"` |
| `cmplz-stats` | `data-category="statistics"` |
| `cmplz-script` | `data-category="marketing"` |

```html
<iframe data-category="marketing" data-service="youtube"></iframe>

<script type="text/plain" data-category="statistics" data-service="matomo"></script>
```

## JavaScript-függvények

| Függvény | Mit csinál |
|---|---|
| `cmplz_has_consent(category)` | Igaz, ha van hozzájárulás a kategóriához vagy szolgáltatáshoz |
| `cmplz_get_banner_status()` | A sütisáv állapota: elvetve vagy megjelenítve |
| `cmplz_set_banner_status(status)` | Beállítja a sütisáv állapotát (megjelenik vagy elvetett), és sütiben tárolja; a paraméter nem kötelező |

## Hookok

```javascript
document.addEventListener("cmplz_enable_category", cmplz_my_custom_hook);
function cmplz_my_custom_hook(consentData) {
  let category = consentData.detail.category;
  let region = consentData.detail.region;
  let acceptedCategories = consentData.detail.categories;

  if (category === 'marketing') {
    // marketing hozzájárulással kapcsolatos teendő
  }
}
```

A legfontosabb hookok:

| Hook | Mikor fut le |
|---|---|
| `cmplz_before_cookiebanner` | a sütisáv futása előtt |
| `cmplz_enable_category` | egy kategória engedélyezésekor (átadja a kategóriát, a kategóriákat és a régiót) |
| `cmplz_tag_manager_event` | Tag Manager eseménynél (a kategóriát adja át) |
| `cmplz_run_after_all_scripts` | az összes szkript betöltése után (a kategóriát adja át) |
| `cmplz_cookie_banner_data` | a sütisáv betöltésekor (a Complianz konfigurációs objektumát adja át) |
| `cmplz_cookie_warning_loaded` | a sütisáv teljes betöltése után (a régiót adja át) |
| `cmplz_status_change` | az állapot változásakor (kategória, kategóriák, régió) |
| `cmplz_revoke` | a hozzájárulás visszavonásakor (átadja, hogy kell-e újratöltés) |

## Saját JavaScript-kódrészlet hozzájáruláshoz kötése

Ha saját JavaScriptet teszel az oldalra, amelynek csak bizonyos hozzájárulás után szabad lefutnia, három lehetőséged van:

1. Add a kódot a **Szkriptközpont** (Script Center) első kódmezőjébe, vagy aszinkron kódnál a másodikba.
2. Használd a Google Tag Managert, és a Complianz eseményindítóit (lásd [Tag Manager kategóriák beállítása](https://hub.hellowp.io/hu/plugins/complianz-gdpr-premium/analitika-consent-mode-gtm-kategoriak/)).
3. Add hozzá a kódot, ahogy akarod, és módosítsd a kódrészletet úgy, hogy a Complianz kezelje.

A harmadik módszer a következő. A 6.0-tól az attribútumokat használd (lásd fent az adatattribútumokat); a régi osztályos megoldás is működik a visszafelé kompatibilitás miatt:

- **Ne blokkolja a Complianz** hozzájárulás előtt: a szkriptcímkére `class="cmplz-native"` kerül, például `<script type="text/javascript" class="cmplz-native">`.
- **Statisztikai hozzájárulásig blokkolja**: `class="cmplz-stats"` és `type="text/plain"`, például `<script type="text/plain" class="cmplz-stats">`.
- **Marketinghozzájárulásig blokkolja**: `class="cmplz-script"` és `type="text/plain"`, például `<script type="text/plain" class="cmplz-script">`.

Példa egy Facebook-pixelre, amely csak marketinghozzájárulás után fut:

```html
<script type="text/plain" class="cmplz-script">
  !function(f,b,e,v,n,t,s)
  {if(f.fbq)return;n=f.fbq=function(){n.callMethod?
  n.callMethod.apply(n,arguments):n.queue.push(arguments)};
  if(!f._fbq)f._fbq=n;n.push=n;n.loaded=!0;n.version='2.0';
  n.queue=[];t=b.createElement(e);t.async=!0;
  t.src=v;s=b.getElementsByTagName(e)[0];
  s.parentNode.insertBefore(t,s)}(window, document,'script',
  'https://connect.facebook.net/en_US/fbevents.js');
  fbq('init', '{a-te-pixel-azonositod}');
  fbq('track', 'PageView');
</script>
```

Az eredeti, blokkolatlan kód ugyanez a `<script>` nyitócímkével, `type` és `class` nélkül.

## A `cmplz_event_all` esemény megszűnése

A `cmplz_event_all` esemény a Tag Manager kategóriáinál használt egyéni esemény: a marketinghez kapcsolódó címkéket indítja, és a nem Tag Manageres oldalakon a konzolnaplóban is látszhat harmadik fél szkriptjeinek aktiválásakor. Ez az esemény megszűnik, és a `cmplz_event_marketing` váltja fel. Az új esemény már használható. A cél ugyanaz marad, csak a név változik. A 4.6.0-tól a böngészőkonzolban, ha az esemény használatban van, ez az üzenet jelenik meg:

```text
Deprecated event: The cmplz_event_all event will be deprecated in the future.
```

Ha a Tag Managerben a `cmplz_event_all` az indító, cseréld `cmplz_event_marketing`-ra. A Tag Manager kategóriáiról a [Tag Manager kategóriák beállítása](https://hub.hellowp.io/hu/plugins/complianz-gdpr-premium/analitika-consent-mode-gtm-kategoriak/) fejezet szól.

## Saját JavaScript-kódrészlet hozzájáruláshoz kötése

Ha saját JavaScriptet teszel az oldalra, amelynek csak bizonyos hozzájárulás után szabad lefutnia, három lehetőséged van:

1. Add a kódot a **Szkriptközpont** (Script Center) első kódmezőjébe, vagy aszinkron kódnál a másodikba.
2. Használd a Google Tag Managert, és a Complianz eseményindítóit (lásd [Tag Manager kategóriák beállítása](https://hub.hellowp.io/hu/plugins/complianz-gdpr-premium/analitika-consent-mode-gtm-kategoriak/)).
3. Add hozzá a kódot, ahogy akarod, és módosítsd a kódrészletet úgy, hogy a Complianz kezelje.

A harmadik módszer a következő. A 6.0-tól az attribútumokat használd (lásd fent az adatattribútumokat); a régi osztályos megoldás is működik a visszafelé kompatibilitás miatt:

- **Ne blokkolja a Complianz** hozzájárulás előtt: a szkriptcímkére `class="cmplz-native"` kerül, például `<script type="text/javascript" class="cmplz-native">`.
- **Statisztikai hozzájárulásig blokkolja**: `class="cmplz-stats"` és `type="text/plain"`, például `<script type="text/plain" class="cmplz-stats">`.
- **Marketinghozzájárulásig blokkolja**: `class="cmplz-script"` és `type="text/plain"`, például `<script type="text/plain" class="cmplz-script">`.

Példa egy Facebook-pixelre, amely csak marketinghozzájárulás után fut:

```html
<script type="text/plain" class="cmplz-script">
  !function(f,b,e,v,n,t,s)
  {if(f.fbq)return;n=f.fbq=function(){n.callMethod?
  n.callMethod.apply(n,arguments):n.queue.push(arguments)};
  if(!f._fbq)f._fbq=n;n.push=n;n.loaded=!0;n.version='2.0';
  n.queue=[];t=b.createElement(e);t.async=!0;
  t.src=v;s=b.getElementsByTagName(e)[0];
  s.parentNode.insertBefore(t,s)}(window, document,'script',
  'https://connect.facebook.net/en_US/fbevents.js');
  fbq('init', '{a-te-pixel-azonositod}');
  fbq('track', 'PageView');
</script>
```

Az eredeti, blokkolatlan kód ugyanez a `<script>` nyitócímkével, `type` és `class` nélkül.

## A `cmplz_event_all` esemény megszűnése

A `cmplz_event_all` esemény a Tag Manager kategóriáinál használt egyéni esemény: a marketinghez kapcsolódó címkéket indítja, és a nem Tag Manageres oldalakon a konzolnaplóban is látszhat harmadik fél szkriptjeinek aktiválásakor. Ez az esemény megszűnik, és a `cmplz_event_marketing` váltja fel. Az új esemény már használható. A cél ugyanaz marad, csak a név változik. A 4.6.0-tól a böngészőkonzolban, ha az esemény használatban van, ez az üzenet jelenik meg:

```text
Deprecated event: The cmplz_event_all event will be deprecated in the future.
```

Ha a Tag Managerben a `cmplz_event_all` az indító, cseréld `cmplz_event_marketing`-ra. A Tag Manager kategóriáiról a [Tag Manager kategóriák beállítása](https://hub.hellowp.io/hu/plugins/complianz-gdpr-premium/analitika-consent-mode-gtm-kategoriak/) fejezet szól.

## Shortcode paraméterek

A hozzájárulási terület shortcode-jának paraméterei: `cache_redirect` (`false` vagy `true`), `category` (például `marketing`) és `text` (a helyőrző szövege). A teljes lista a [Hozzájárulási terület](https://hub.hellowp.io/hu/plugins/complianz-gdpr-premium/fejlesztoknek-hozzajarulasi-terulet/) fejezetben van.

## PHP

```php
// igaz, ha van hozzájárulás a kategóriához
cmplz_has_consent( $category );
```

## Saját integráció létrehozása

Az integrációs API-val a felhasználó teljes kontrollt kap: az integráció megjelenik az integrációs központban, ahol bekapcsolhatja, vagy a helyőrzőt be- és kikapcsolhatja. A példa egy Google Maps bővítmény (MapPress).

### 1. Az integráció bejelentése

Add hozzá a bővítményed az integrációkhoz a `cmplz_integrations` szűrővel. A példában a MapPress konstansa jelzi, hogy a bővítmény aktív; ez lehet függvény vagy osztálynév is, de a bővítmény fő fájljában kell deklarálni, különben a Complianz nem észleli.

```php
function my_plugin_integration( $cmplz_integrations_list ) {
    $cmplz_integrations_list['mappress'] = array(
        'constant_or_function' => 'Mappress',
        'label'                => 'MapPress Maps for WordPress',
        'firstparty_marketing' => false,
    );
    return $cmplz_integrations_list;
}
add_filter( 'cmplz_integrations', 'my_plugin_integration' );
```

### 2. Az integrációs fájl helye

Mondd meg a Complianznak, hol van az integrációs fájl. A `$plugin` az integrációs tömb kulcsa (itt `mappress`). Hozz létre a bővítményedben egy fájlt (például `complianz.php`), és add meg az útvonalát. Így a Complianz be tudja tölteni, és az integrációs áttekintőből a Complianz vagy a bővítmény kikapcsolása nélkül is kikapcsolható.

```php
function my_plugin_integration_path( $path, $plugin ) {
    if ( $plugin === 'mappress' ) {
        return 'my_plugin_path/complianz.php';
    }
    return $path;
}
add_filter( 'cmplz_integration_path', 'my_plugin_integration_path', 10, 2 );
```

### 3. Az integráció elkészítése

A fájl elején védd a közvetlen elérést:

```php
<?php
defined( 'ABSPATH' ) or die( "you do not have access to this page!" );
```

Szkript blokkolásához a `cmplz_known_script_tags` szűrővel új elemet adsz a tömbhöz. Minden olyan URL-t, amelyet hozzájárulás nélkül blokkolni kell, az `urls` indexbe tegyél: lehet beágyazott szkript részlete vagy a forrás URL-jének egy egyedi része. Az új elemnek mindig kell neve, kategóriája és legalább egy URL-je.

```php
function cmplz_mappress_script( $tags ) {
    $tags[] = array(
        'name'               => 'mappress',
        'category'           => 'marketing',
        'urls'               => array(
            'mappress-google-maps-for-wordpress/js/mappress',
        ),
        'enable_placeholder' => '1',
        'placeholder'        => 'google-maps',
        'placeholder_class'  => 'mapp-canvas-panel',
        'enable_dependency'  => '0',
    );
    return $tags;
}
add_filter( 'cmplz_known_script_tags', 'cmplz_mappress_script' );
```

#### Helyőrző hozzáadása

A példában a meglévő `google-maps` helyőrzőt választottuk. Az összes helyőrző a bővítmény `assets/images/placeholders` mappájában található. A `mapp-canvas-panel` osztály rakja a képet a div-re, ezért egyedinek kell lennie. Az `enable_placeholder` értéke `1`, a `placeholder_class` az osztály.

Saját helyőrzőt is megadhatsz: a `cmplz_placeholder_<szolgáltatás>` szűrő felülírja az `images/placeholders` mappa tartalmát. Átadja az észlelt forrást és a javasolt újat, te egészen mást is visszaadhatsz.

```php
function cmplz_google_maps_placeholder( $new_src, $src ) {
    // az egyedi helyőrző útvonala
    return $new_src;
}
add_filter( 'cmplz_placeholder_google-maps', 'cmplz_google_maps_placeholder', 10, 2 );
```

Itt egy kis egyedi CSS is kell, hogy a helyőrző jól jelenjen meg:

```php
function cmplz_mapppress_css() {
    ?>
    .mapp-main .cmplz-placeholder-element {
        height: 100%;
        width: 100%;
    }
    <?php
}
add_action( 'cmplz_banner_css', 'cmplz_mapppress_css' );
```

**Egyedi elemek és webkomponensek.** A helyőrző bármilyen érvényes HTML-elemhez kapcsolható, egyedi elemekhez és webkomponensekhez is (például `<mappress-map>`). A címkét nem kell sehol regisztrálni: ha az elemnek megvan a szkriptcímkében megadott `placeholder_class`, a Complianz hozzájárulás hiányában arra teszi a helyőrzőt.

```php
add_filter( 'cmplz_known_script_tags', function( $tags ) {
    $tags[] = [
        'name'               => 'my-service',
        'category'           => 'marketing',
        'placeholder'        => 'google-maps',
        'urls'               => [ 'my-service.com' ],
        'enable_placeholder' => '1',
        'placeholder_class'  => 'my-widget-class',
    ];
    return $tags;
} );
```

```html
<my-widget class="my-widget-class">
  Minden, ami itt van, a helyőrző mögött rejtve marad,
  amíg a látogató nem járul hozzá.
</my-widget>
```

#### A szolgáltatás felvétele

Ez nem kötelező, de hasznos: ha hozzáadod ezt a szűrőt, a bővítmény automatikusan felveszi a „Google Maps” szolgáltatást az észlelt szolgáltatások közé, így alapértelmezetté válik, és megjelenik a róla szóló értesítésben. A közösségi médiához a `cmplz_detected_social_media`, a statisztikához a `cmplz_detected_stats_type` hook tartozik.

```php
function cmplz_mappress_detected_services( $services ) {
    if ( ! in_array( 'google-maps', $services ) ) {
        $services[] = 'google-maps';
    }
    return $services;
}
add_filter( 'cmplz_detected_services', 'cmplz_mappress_detected_services' );
```

#### Függőségek

Néha a szkriptek hozzájárulás után rossz sorrendben töltődnek be, és JavaScript-hibát okoznak („undefined function”, „undefined constant”). Ilyenkor megadhatod, melyik szkript melyikre várjon. A példában a `wpgmp_map` részletet tartalmazó beágyazott szkriptnek meg kell várnia a `maps.js` fájlt, mert az onnan vár egy változót. Állítsd az `enable_dependency` értékét `1`-re, és add meg a `dependency` tömböt (`'a-szkript-amire-varni-kell' => 'a-varakozo-szkript'` párokkal). A részletnek elég egyedinek kell lennie.

```php
function cmplz_mappress_script( $tags ) {
    $tags[] = array(
        'name'               => 'mappress',
        'category'           => 'marketing',
        'placeholder'        => 'google-maps',
        'urls'               => array(
            'mappress-google-maps-for-wordpress/js/mappress',
        ),
        'enable_placeholder' => '1',
        'placeholder_class'  => 'mapp-canvas-panel',
        'enable_dependency'  => '1',
        'dependency'         => [
            'maps.js' => 'wpgmp_map',
        ],
    );
    return $tags;
}
add_filter( 'cmplz_known_script_tags', 'cmplz_mappress_script' );
```

Így teljes értékű integrációt kapsz, amely a Complianz integrációs vezérlőpultján kezelhető. A MapPress és más integrációk teljes kódja a Complianz bővítménymappájában, az `integrations/plugins` alatt található.