Manajemen fitur JavaScript

Pustaka manajemen fitur JavaScript menyediakan cara untuk mengembangkan dan mengekspos fungsionalitas aplikasi berdasarkan bendera fitur. Setelah fitur baru dikembangkan, banyak aplikasi memiliki persyaratan khusus, seperti kapan fitur harus diaktifkan dan dalam kondisi apa. Pustaka ini menyediakan cara untuk menentukan hubungan ini, dan juga terintegrasi ke dalam pola kode JavaScript umum untuk memungkinkan mengekspos fitur-fitur ini.

Bendera fitur menyediakan cara bagi aplikasi JavaScript untuk mengaktifkan atau menonaktifkan fitur secara dinamis. Pengembang dapat menggunakan bendera fitur dalam kasus penggunaan sederhana seperti pernyataan kondisional.

Berikut adalah beberapa manfaat menggunakan pustaka manajemen fitur JavaScript:

• Konvensi umum untuk manajemen fitur
• Hambatan masuk yang rendah
  • Mendukung objek JSON dan sumber bendera fitur berbasis peta
  • Mendukung penggunaan di lingkungan Node.js dan browser
• Manajemen masa pakai bendera fitur dengan Azure App Configuration
  • Nilai konfigurasi dapat berubah secara real time
• Skenario sederhana hingga kompleks tercakup
  • Mengaktifkan/menonaktifkan fitur melalui file konfigurasi deklaratif
  • Mengevaluasi status fitur secara dinamis berdasarkan panggilan ke server

Pustaka manajemen fitur JavaScript sumber terbuka. Untuk informasi selengkapnya, kunjungi repositori GitHub.

Catatan

Disarankan untuk menggunakan pustaka manajemen fitur bersama dengan Azure App Configuration. Azure App Configuration menyediakan solusi untuk mengelola pengaturan aplikasi dan bendera fitur secara terpusat. Untuk detail selengkapnya, silakan merujuk ke bagian ini.

Bendera fitur

Bendera fitur terdiri dari dua bagian, nama dan daftar filter fitur yang digunakan untuk mengaktifkan fitur.

Filter berdasarkan fitur

Filter fitur menentukan skenario kapan fitur harus diaktifkan. Ketika fitur dievaluasi apakah fitur tersebut aktif atau nonaktif, daftar filter fiturnya dilalui hingga salah satu filter memutuskan fitur harus diaktifkan. Pada titik ini, fitur ini dianggap sebagai aktif dan proses traversing melalui filter fitur berhenti. Jika tidak ada filter fitur yang menunjukkan bahwa fitur harus diaktifkan, filter tersebut dianggap dinonaktifkan.

Sebagai contoh, filter fitur browser Microsoft Edge dapat dirancang. Filter fitur ini akan mengaktifkan fitur apa pun yang terpasang padanya, selama permintaan HTTP berasal dari Microsoft Edge.

Konfigurasi penanda fitur

Di JavaScript, pengembang biasanya menggunakan objek atau peta sebagai struktur data utama untuk mewakili konfigurasi. Pustaka manajemen fitur JavaScript mendukung kedua pendekatan konfigurasi, memberi pengembang fleksibilitas untuk memilih opsi yang paling sesuai dengan kebutuhan mereka. FeatureManager dapat membaca flag fitur dari berbagai jenis konfigurasi menggunakan fitur bawaan ConfigurationObjectFeatureFlagProvider dan ConfigurationMapFeatureFlagProvider.

Menggunakan konfigurasi peta

const config = new Map([
    ["feature_management", {
        "feature_flags": [
            {
                "id": "FeatureT",
                "enabled": true
            },
            {
                "id": "FeatureU",
                "enabled": false
            }
        ]
    }],
    ["some other configuration", " some value"]
]);

import { ConfigurationMapFeatureFlagProvider, FeatureManager } from "@microsoft/feature-management";
const featureProvider = new ConfigurationMapFeatureFlagProvider(config);
const featureManager = new FeatureManager(featureProvider);

Menggunakan konfigurasi objek

const config = {
    "feature_management": {
        "feature_flags": [
            {
                "id": "FeatureT",
                "enabled": true
            },
            {
                "id": "FeatureX",
                "enabled": false
            }
        ]
    },
    "some other configuration": " some value"
}

import { ConfigurationObjectFeatureFlagProvider, FeatureManager } from "@microsoft/feature-management";
const featureProvider = new ConfigurationObjectFeatureFlagProvider(config);
const featureManager = new FeatureManager(featureProvider);

Objek juga dapat diurai dari file JSON:

const config = JSON.parse(await fs.readFile("path/to/config.json"));
const featureProvider = new ConfigurationObjectFeatureFlagProvider(config);
const featureManager = new FeatureManager(featureProvider);

Menggunakan bendera fitur dari Azure App Configuration

Daripada mengkodekan bendera fitur Anda ke dalam aplikasi, kami sarankan menyimpan bendera fitur di luar aplikasi dan mengelola bendera fitur secara terpisah. Dengan melakukan hal tersebut memungkinkan Anda untuk mengubah status bendera kapan saja dan membuat perubahan tersebut berlaku di aplikasi dengan segera. Layanan Azure App Configuration menyediakan UI portal khusus untuk mengelola semua bendera fitur Anda. Lihatlah tutorial.

Layanan Azure App Configuration juga mengirimkan feature flags langsung ke aplikasi Anda melalui pustaka klien JavaScript @azure/app-configuration-provider. Contoh berikut menunjukkan cara menggunakan pustaka.

Penyedia JavaScript App Configuration menyediakan bendera fitur dalam Map objek. Fungsi bawaan ConfigurationMapFeatureFlagProvider membantu memuat flag fitur dalam kasus ini.

import { DefaultAzureCredential } from "@azure/identity";
import { load } from "@azure/app-configuration-provider";
import { ConfigurationMapFeatureFlagProvider, FeatureManager } from "@microsoft/feature-management";
const appConfig = await load("YOUR_APP-CONFIG-ENDPOINT",
                             new DefaultAzureCredential(), // For more information: https://learn.microsoft.com/javascript/api/overview/azure/identity-readme
                             { featureFlagOptions: { enabled: true } }); // load feature flags from Azure App Configuration service
const featureProvider = new ConfigurationMapFeatureFlagProvider(appConfig);
const featureManager = new FeatureManager(featureProvider);

Menggunakan Azure App Configuration untuk mengontrol status bendera fitur secara dinamis

Azure App Configuration bukan hanya solusi untuk eksternalisasi penyimpanan dan manajemen terpusat bendera fitur Anda, tetapi juga memungkinkan Anda untuk mengaktifkan/menonaktifkan bendera fitur secara dinamis.

Untuk mengaktifkan refresh dinamis untuk bendera fitur, Anda perlu mengonfigurasi refresh properti featureFlagOptions saat memuat bendera fitur dari Azure App Configuration.

const appConfig = await load("YOUR_APP-CONFIG-ENDPOINT",  new DefaultAzureCredential(),  { 
    featureFlagOptions: { 
        enabled: true,
        refresh: {
            enabled: true, // enable the dynamic refresh for feature flags
            refreshIntervalInMs: 30_000
        }
    } 
});

const featureProvider = new ConfigurationMapFeatureFlagProvider(appConfig);
const featureManager = new FeatureManager(featureProvider);

Anda perlu memanggil refresh metode untuk mendapatkan status bendera fitur terbaru.

await appConfig.refresh(); // Refresh to get the latest feature flags
const isBetaEnabled = await featureManager.isEnabled("Beta");
console.log(`Beta is enabled: ${isBetaEnabled}`);

Catatan

Untuk informasi selengkapnya tentang cara menggunakan pustaka manajemen fitur dengan Azure App Configuration, silakan merujuk ke panduan memulai cepat.

Deklarasi bendera fitur

Contoh berikut menunjukkan format yang digunakan untuk menyiapkan bendera fitur dalam file JSON.

{
    "feature_management": {
        "feature_flags": [
            {
                "id": "FeatureT",
                "enabled": true
            },
            {
                "id": "FeatureU",
                "enabled": false
            },
            {
                "id": "FeatureV",
                "enabled": true,
                "conditions": {
                    "client_filters": [
                        {
                            "name": "Microsoft.TimeWindow",
                            "parameters": {
                                "Start": "Wed, 01 May 2019 13:59:59 GMT",
                                "End": "Mon, 01 Jul 2019 00:00:00 GMT"
                            }
                        }
                    ]
                }
            }
        ]
    }
}

Bagian feature_management ini digunakan oleh konvensi untuk memuat pengaturan bendera fitur. Bagian feature_flags ini adalah daftar bendera fitur yang dimuat ke dalam pustaka. Di bagian di atas, kita melihat tiga fitur berbeda. Fitur-fitur mendefinisikan filter fitur mereka dengan menggunakan properti client_filters, di dalam conditions. Dalam filter fitur untuk FeatureT, kita lihat enabled adalah true dengan tidak adanya filter yang ditentukan, yang menghasilkan FeatureT selalu mengembalikan true. FeatureU sama seperti FeatureT, tetapi dengan enabled adalah false yang menyebabkan fitur selalu mengembalikan false. FeatureV menentukan filter fitur bernama Microsoft.TimeWindow. FeatureV adalah contoh filter fitur yang dapat dikonfigurasi. Kita dapat melihat dalam contoh bahwa filter memiliki parameters properti . Properti parameters digunakan untuk mengonfigurasi filter. Dalam hal ini, waktu mulai dan berakhir agar fitur aktif dikonfigurasi.

Skema terperinci dari feature_management bagian dapat ditemukan di sini.

Tingkat Lanjut: Penggunaan titik dua ':' dilarang dalam nama bendera fitur.

Jenis persyaratan

Properti requirement_type bendera fitur digunakan untuk menentukan apakah filter harus menggunakan Any atau All logika saat mengevaluasi status fitur. Jika requirement_type tidak ditentukan, nilai defaultnya adalah Any.

• Any berarti hanya satu filter yang perlu dievaluasi ke true agar fitur diaktifkan.
• All berarti setiap filter perlu mengevaluasi ke true agar fitur diaktifkan.

Sebuah requirement_type dari All mengubah traversal. Pertama, jika tidak ada filter, fitur dinonaktifkan. Kemudian, filter fitur dilalui hingga salah satu filter memutuskan bahwa fitur harus dinonaktifkan. Jika tidak ada filter yang menunjukkan bahwa fitur harus dinonaktifkan, fitur tersebut dianggap diaktifkan.

{
    "feature_management": {
        "feature_flags": [
            {
                "id": "FeatureW",
                "enabled": true,
                "conditions": {
                    "requirement_type": "All",
                    "client_filters": [
                        {
                            "name": "Microsoft.TimeWindow",
                            "parameters": {
                                "Start": "Wed, 01 May 2019 13:59:59 GMT",
                                "End": "Mon, 01 Jul 2019 00:00:00 GMT"
                            }
                        },
                        {
                            "name": "Percentage",
                            "parameters": {
                                "Value": "50"
                            }
                        }
                    ]
                }
            },
        ]
    }
}

Dalam contoh di atas, FeatureW menentukan requirement_type dari All, yang berarti semua filternya harus dievaluasi menjadi benar agar fitur diaktifkan. Dalam hal ini, fitur diaktifkan untuk 50% pengguna selama jendela waktu yang ditentukan.

Konsumsi

Bentuk dasar manajemen fitur adalah memeriksa apakah flag fitur diaktifkan dan kemudian melakukan tindakan berdasarkan hasilnya. Memeriksa status flag fitur dilakukan melalui metode FeatureManagerisEnabled.

Menggunakan konfigurasi peta

import { ConfigurationMapFeatureFlagProvider, FeatureManager } from "@microsoft/feature-management";
const featureProvider = new ConfigurationMapFeatureFlagProvider(config);
const featureManager = new FeatureManager(featureProvider);

const isBetaEnabled = await featureManager.isEnabled("Beta");
if (isBetaEnabled) {
    // Do something
}

Menggunakan konfigurasi objek

import { ConfigurationObjectFeatureFlagProvider, FeatureManager } from "@microsoft/feature-management";
const featureProvider = new ConfigurationObjectFeatureFlagProvider(config);
const featureManager = new FeatureManager(featureProvider);

const isBetaEnabled = await featureManager.isEnabled("Beta");
if (isBetaEnabled) {
    // Do something
}

Menerapkan filter fitur

Membuat filter fitur menyediakan cara untuk mengaktifkan fitur berdasarkan kriteria yang Anda tentukan. Untuk menerapkan filter fitur, IFeatureFilter antarmuka harus diimplementasikan. IFeatureFilter memiliki name properti dan metode bernama evaluate. name harus digunakan dalam konfigurasi untuk mereferensikan filter fitur dalam bendera fitur. Ketika fitur menentukan bahwa fitur tersebut dapat diaktifkan untuk filter fitur, evaluate metode dipanggil. Jika evaluate mengembalikan true, itu berarti fitur harus diaktifkan.

interface IFeatureFilter {
    name: string;
    evaluate(context: IFeatureFilterEvaluationContext, appContext?: unknown): boolean | Promise<boolean>;
}

Cuplikan berikut menunjukkan cara mengimplementasikan filter fitur yang disesuaikan dengan nama MyCriteria.

    class MyCriteriaFilter {
        name = "MyCriteria";
        evaluate(context, appContext) {
            if (satisfyCriteria()) {
                return true;
            }
            else {
                return false;
            }
        }
    }

Anda perlu mendaftarkan filter kustom di bawah properti customFilters dari objek FeatureManagerOptions yang diteruskan ke konstruktor FeatureManager.

const featureManager = new FeatureManager(ffProvider, {
    customFilters: [
        new MyCriteriaFilter() // add custom feature filters under FeatureManagerOptions.customFilters
    ]
});

Filter fitur berparameter

Beberapa filter fitur memerlukan parameter untuk memutuskan apakah fitur harus diaktifkan atau tidak. Misalnya, filter fitur browser dapat mengaktifkan fitur untuk sekumpulan browser tertentu. Mungkin diinginkan bahwa browser Edge dan Chrome mengaktifkan fitur, sementara Firefox tidak. Untuk melakukan ini, filter fitur dapat dirancang untuk mengharapkan parameter. Parameter ini akan ditentukan dalam konfigurasi fitur, dan dalam kode akan dapat diakses melalui IFeatureFilterEvaluationContext parameter IFeatureFilter.Evaluate.

interface IFeatureFilterEvaluationContext {
    featureName: string;
    parameters?: unknown;
}

IFeatureFilterEvaluationContext memiliki properti bernama parameters. Parameter ini mewakili konfigurasi mentah yang dapat digunakan filter fitur untuk memutuskan cara mengevaluasi apakah fitur harus diaktifkan atau tidak. Untuk menggunakan filter fitur browser sebagai contoh sekali lagi, filter dapat digunakan parameters untuk mengekstrak sekumpulan browser yang diizinkan yang akan ditentukan untuk fitur tersebut dan kemudian memeriksa apakah permintaan dikirim dari salah satu browser tersebut.

Menggunakan konteks aplikasi untuk evaluasi fitur

Filter fitur mungkin memerlukan konteks aplikasi runtime untuk mengevaluasi bendera fitur. Anda dapat meneruskan konteks sebagai parameter saat memanggil isEnabled.

featureManager.isEnabled("Beta", { userId : "Sam" })

Filter fitur dapat memanfaatkan konteks yang diteruskan saat isEnabled dipanggil. Konteks aplikasi akan diteruskan sebagai parameter kedua dari IFeatureFilter.Evaluate.

Filter fitur bawaan

Ada dua filter fitur yang disertakan dalam paket FeatureManagement: TimeWindowFilter dan TargetingFilter. Semua filter fitur bawaan akan ditambahkan secara default saat membuat FeatureManager.

Masing-masing filter fitur bawaan memiliki parameternya sendiri. Berikut adalah daftar filter fitur bersama dengan contoh.

Microsoft.TimeWindow

Filter ini menyediakan kemampuan untuk mengaktifkan fitur berdasarkan jendela waktu. Jika hanya End ditentukan, fitur dianggap aktif hingga waktu tersebut. Jika hanya Start ditentukan, fitur dianggap aktif di semua titik setelah waktu tersebut.

"client_filters": [
    {
        "name": "Microsoft.TimeWindow",
        "parameters": {
            "Start": "Wed, 01 May 2019 13:59:59 GMT",
            "End": "Mon, 01 Jul 2019 00:00:00 GMT"
        }
    }
]     

Jendela waktu dapat dikonfigurasi untuk berulang secara berkala. Ini dapat berguna untuk skenario di mana seseorang mungkin perlu mengaktifkan fitur selama periode lalu lintas rendah atau tinggi dalam sehari atau hari-hari tertentu dalam seminggu. Untuk memperluas jendela waktu individual ke jendela waktu berulang, aturan pengulangan harus ditentukan dalam Recurrence parameter .

Catatan

Start dan End harus ditentukan untuk mengaktifkan Recurrence.

"client_filters": [
    {
        "name": "Microsoft.TimeWindow",
        "parameters": {
            "Start": "Fri, 22 Mar 2024 20:00:00 GMT",
            "End": "Sat, 23 Mar 2024 02:00:00 GMT",
            "Recurrence": {
                "Pattern": {
                    "Type": "Daily",
                    "Interval": 1
                },
                "Range": {
                    "Type": "NoEnd"
                }
            }
        }
    }
]

Pengaturan Recurrence terdiri dari dua bagian: Pattern (seberapa sering jendela waktu berulang) dan Range (selama pola pengulangan berulang).

Pola Pengulangan

Ada dua kemungkinan jenis pola pengulangan: Daily dan Weekly. Misalnya, jendela waktu dapat mengulangi "setiap hari", "setiap tiga hari", "setiap Senin" atau "setiap Jumat lainnya".

Bergantung pada jenisnya, bidang Pattern tertentu yang diperlukan, opsional, atau diabaikan.

• Daily

  Pola pengulangan harian menyebabkan jendela waktu diulang berdasarkan sejumlah hari di antara setiap kemunculan.

  Properti	Relevansi	Deskripsi
  Type	Diperlukan	Harus diatur ke Daily.
  Interval	Fakultatif	Menentukan jumlah hari di antara setiap kemunculan. Nilai defaultnya adalah 1.

• Weekly

  Pola pengulangan mingguan menyebabkan jendela waktu diulang pada hari atau hari yang sama dalam seminggu, berdasarkan jumlah minggu antara setiap set kemunculan.

  Properti	Relevansi	Deskripsi
  Type	Diperlukan	Harus diatur ke Weekly.
  DaysOfWeek	Diperlukan	Menentukan hari dalam seminggu peristiwa terjadi.
  Interval	Fakultatif	Menentukan jumlah minggu antara setiap rangkaian kemunculan. Nilai defaultnya adalah 1.
  FirstDayOfWeek	Fakultatif	Menentukan hari mana yang dianggap sebagai hari pertama dalam seminggu. Nilai defaultnya adalah Sunday.

  Contoh berikut mengulangi jendela waktu setiap Senin dan Selasa lainnya

  "Pattern": {
      "Type": "Weekly",
      "Interval": 2,
      "DaysOfWeek": ["Monday", "Tuesday"]
  }
  

Catatan

Start harus merupakan kemunculan pertama yang valid yang sesuai dengan pola pengulangan. Selain itu, durasi jendela waktu tidak boleh lebih lama dari seberapa sering itu terjadi. Misalnya, tidak valid untuk memiliki jendela waktu 25 jam berulang setiap hari.

Rentang Pengulangan

Ada tiga kemungkinan jenis rentang pengulangan: NoEnd, EndDate dan Numbered.

• NoEnd

  Rentang NoEnd menyebabkan pengulangan terjadi tanpa batas waktu.

  Properti	Relevansi	Deskripsi
  Type	Diperlukan	Harus diatur ke NoEnd.

• EndDate

  Rentang EndDate menyebabkan jendela waktu terjadi pada semua hari yang sesuai dengan pola yang berlaku hingga tanggal akhir.

  Properti	Relevansi	Deskripsi
  Type	Diperlukan	Harus diatur ke EndDate.
  Tanggal Akhir	Diperlukan	Menentukan waktu tanggal untuk berhenti menerapkan pola. Selama waktu mulai kejadian terakhir jatuh sebelum tanggal akhir, waktu akhir kejadian tersebut diizinkan untuk meluas di luarnya.

  Contoh berikut akan mengulangi jendela waktu setiap hari hingga kejadian terakhir terjadi pada 1 April 2024.

  "Start": "Fri, 22 Mar 2024 18:00:00 GMT",
  "End": "Fri, 22 Mar 2024 20:00:00 GMT",
  "Recurrence":{
      "Pattern": {
          "Type": "Daily",
          "Interval": 1
      },
      "Range": {
          "Type": "EndDate",
          "EndDate": "Mon, 1 Apr 2024 20:00:00 GMT"
      }
  }
  

• Numbered

  Rentang Numbered menyebabkan jendela waktu terjadi berapa kali (berdasarkan pola).

  Properti	Relevansi	Deskripsi
  Type	Diperlukan	Harus diatur ke Numbered.
  NumberOfOccurrences	Diperlukan	Menentukan jumlah kemunculan.

  Contoh berikut akan mengulangi jendela waktu pada hari Senin dan Selasa hingga ada tiga kemunculan, yang masing-masing terjadi pada 1 April (Senin), 2 April (Selasa) dan 8 April (Senin).

  "Start": "Mon, 1 Apr 2024 18:00:00 GMT",
  "End": "Mon, 1 Apr 2024 20:00:00 GMT",
  "Recurrence":{
      "Pattern": {
          "Type": "Weekly",
          "Interval": 1,
          "DaysOfWeek": ["Monday", "Tuesday"]
      },
      "Range": {
          "Type": "Numbered",
          "NumberOfOccurrences": 3
      }
  }
  

Untuk membuat aturan pengulangan, Anda harus menentukan dan PatternRange. Jenis pola apa pun dapat bekerja dengan jenis rentang apa pun.

Maju: Offset Start zona waktu properti diterapkan ke pengaturan pengulangan.

Microsoft.Targeting

Filter ini menyediakan kemampuan untuk mengaktifkan fitur untuk audiens target. Penjelasan mendalam tentang penargetan dijelaskan di bagian penargetan di bawah ini. Parameter filter mencakup Audience objek yang menjelaskan pengguna, grup, pengguna/grup yang dikecualikan, dan persentase default dari basis pengguna yang harus memiliki akses ke fitur tersebut. Setiap objek grup yang tercantum di bagian Groups juga harus menentukan persentase anggota grup apa yang harus memiliki akses. Jika pengguna ditentukan di bagian Exclusion , baik secara langsung atau jika pengguna berada dalam grup yang dikecualikan, fitur dinonaktifkan. Jika tidak, jika pengguna ditentukan di bagian Users secara langsung, atau jika pengguna termasuk dalam persentase yang disertakan dari salah satu peluncuran grup, atau jika pengguna termasuk dalam persentase peluncuran default, maka fitur tersebut akan diaktifkan untuk pengguna tersebut.

"client_filters": [
    {
        "name": "Microsoft.Targeting",
        "parameters": {
            "Audience": {
                "Users": [
                    "Jeff",
                    "Alicia"
                ],
                "Groups": [
                    {
                        "Name": "Ring0",
                        "RolloutPercentage": 100
                    },
                    {
                        "Name": "Ring1",
                        "RolloutPercentage": 50
                    }
                ],
                "DefaultRolloutPercentage": 20,
                "Exclusion": {
                    "Users": [
                        "Ross"
                    ],
                    "Groups": [
                        "Ring2"
                    ]
                }
            }
        }
    }
]

Penargetan

Penargetan adalah strategi manajemen fitur yang memungkinkan pengembang untuk secara progresif meluncurkan fitur baru ke basis pengguna mereka. Strategi ini dibangun berdasarkan konsep menargetkan sekumpulan pengguna yang dikenal sebagai audiens target. Audiens terdiri dari pengguna tertentu, grup, pengguna/grup yang dikecualikan, dan persentase yang ditunjuk dari seluruh basis pengguna. Grup yang disertakan dalam audiens dapat dipecah lebih jauh ke dalam persentase dari total anggota mereka.

Langkah-langkah berikut menunjukkan contoh peluncuran progresif untuk fitur 'Beta' baru:

1. Pengguna individu Jeff dan Alicia diberikan akses ke Beta.
2. Pengguna lain, Mark, meminta untuk ikut serta dan disertakan.
3. Dua puluh persen dari grup yang dikenal sebagai pengguna "Ring1" disertakan dalam Beta.
4. Jumlah pengguna "Ring1" yang ikut dalam Beta ditingkatkan hingga 100 Persen.
5. Lima persen dari basis pengguna disertakan dalam Beta.
6. Persentase peluncuran dinaikkan menjadi 100 persen dan fitur ini sepenuhnya diluncurkan.

Strategi untuk meluncurkan fitur ini dibangun dalam pustaka dengan filter fitur Microsoft.Targeting yang disertakan.

Menargetkan pengguna dengan konteks penargetan

Filter penargetan bergantung pada konteks penargetan untuk mengevaluasi apakah fitur harus diaktifkan. Konteks penargetan ini berisi informasi seperti pengguna apa yang saat ini sedang dievaluasi, dan grup tempat pengguna berada. Konteks penargetan harus diteruskan langsung ketika isEnabled dipanggil.

featureManager.isEnabled("Beta", { userId: "Aiden", groups: ["Ring1"] })

Menargetkan pengecualian

Saat menentukan audiens, pengguna dan grup dapat dikecualikan dari audiens. Pengecualian berguna saat fitur diluncurkan ke sekelompok pengguna, tetapi beberapa pengguna atau grup perlu dikecualikan dari peluncuran. Pengecualian didefinisikan dengan menambahkan daftar pengguna dan grup ke properti Exclusion dari audiens.

"Audience": {
    "Users": [
        "Jeff",
        "Alicia"
    ],
    "Groups": [
        {
            "Name": "Ring0",
            "RolloutPercentage": 100
        }
    ],
    "DefaultRolloutPercentage": 0,
    "Exclusion": {
        "Users": [
            "Mark"
        ]
    }
}

Dalam contoh di atas, fitur diaktifkan untuk pengguna bernama Jeff dan Alicia. Ini juga diaktifkan untuk pengguna dalam grup bernama Ring0. Namun, jika pengguna diberi nama Mark, fitur dinonaktifkan, terlepas dari apakah mereka berada dalam grup Ring0 atau tidak. Pengecualian lebih diprioritaskan daripada filter penargetan lainnya.

Penargetan dalam Aplikasi Web

Contoh aplikasi web yang menggunakan filter fitur penargetan tersedia dalam contoh proyek ini.

Dalam aplikasi web, terutama yang memiliki beberapa komponen atau lapisan, meneruskan konteks penargetan (userId dan groups) ke setiap pemeriksaan bendera fitur dapat menjadi rumit dan berulang. Skenario ini disebut sebagai "konteks penargetan sekitar", di mana informasi identitas pengguna sudah tersedia dalam konteks aplikasi (seperti dalam data sesi atau konteks autentikasi) tetapi perlu dapat diakses oleh evaluasi manajemen fitur di seluruh aplikasi.

ITargetingContextAccessor

Pustaka menyediakan solusi melalui ITargetingContextAccessor pola.

interface ITargetingContext {
    userId?: string;
    groups?: string[];
}

interface ITargetingContextAccessor {
    getTargetingContext: () => ITargetingContext | undefined;
}

Daripada meneruskan konteks penargetan secara eksplisit pada setiap panggilan isEnabled atau getVariant, Anda dapat memberikan fungsi yang mengetahui cara mengambil informasi penargetan pengguna saat ini dari konteks aplikasi Anda:

import { FeatureManager, ConfigurationObjectFeatureFlagProvider } from "@microsoft/feature-management";

// Create a targeting context accessor that uses your application's auth system
const targetingContextAccessor = {
    getTargetingContext: () => {
        // In a web application, this might access request context or session data
        // This is just an example - implement based on your application's architecture
        return {
            userId: getCurrentUserId(), // Your function to get current user
            groups: getUserGroups()     // Your function to get user groups
        };
    }
};

// Configure the feature manager with the accessor
const featureManager = new FeatureManager(featureProvider, {
    targetingContextAccessor: targetingContextAccessor
});

// Now you can call isEnabled without explicitly providing targeting context
// The feature manager will use the accessor to get the current user context
const isBetaEnabled = await featureManager.isEnabled("Beta");

Pola ini sangat berguna dalam aplikasi web sisi server di mana konteks pengguna dapat tersedia dalam cakupan permintaan atau di aplikasi klien tempat identitas pengguna dikelola secara terpusat.

Menggunakan AsyncLocalStorage untuk konteks permintaan

Salah satu tantangan umum saat menerapkan pola pengakses konteks penargetan adalah mempertahankan konteks permintaan di seluruh rantai panggilan asinkron. Dalam aplikasi web Node.js, informasi identitas pengguna biasanya tersedia di objek permintaan, tetapi menjadi tidak dapat diakses setelah Anda memasukkan operasi asinkron.

Node.js menyediakan AsyncLocalStorage dari async_hooks modul untuk menyelesaikan masalah ini. Ini membuat ruang penyimpanan yang konsisten di seluruh operasi asinkron dalam "konteks" logis yang sama - ideal untuk menjaga data tetap konsisten selama seluruh siklus permintaan.

Berikut cara menerapkan akses konteks penargetan menggunakan AsyncLocalStorage dalam aplikasi Express.js:

import { AsyncLocalStorage } from "async_hooks";
import express from "express";

const requestAccessor = new AsyncLocalStorage();

const app = express();
// Middleware to store request context
app.use((req, res, next) => {
    // Store the request in AsyncLocalStorage for this request chain
    requestAccessor.run(req, () => {
        next();
    });
});

// Create targeting context accessor that retrieves user data from the current request
const targetingContextAccessor = {
    getTargetingContext: () => {
        // Get the current request from AsyncLocalStorage
        const request = requestAccesor.getStore();
        if (!request) {
            return undefined; // Return undefined if there's no current request
        }
        // Extract user data from request (from session, auth token, etc.)
        return {
            userId: request.user?.id,
            groups: request.user?.groups || []
        };
    }
};

Varian

Ketika fitur baru ditambahkan ke aplikasi, mungkin ada saatnya ketika fitur memiliki beberapa opsi desain yang diusulkan berbeda. Solusi umum untuk memutuskan desain adalah beberapa bentuk pengujian A/B, yang melibatkan penyediaan versi fitur yang berbeda ke segmen yang berbeda dari basis pengguna dan memilih versi berdasarkan interaksi pengguna. Dalam pustaka ini, fungsionalitas ini diaktifkan dengan mewakili konfigurasi-konfigurasi berbeda dari sebuah fitur dengan variannya.

Varian memungkinkan bendera fitur menjadi lebih dari bendera aktif/nonaktif sederhana. Varian mewakili nilai bendera fitur yang dapat berupa string, angka, boolean, atau bahkan objek konfigurasi. Bendera fitur yang menyatakan varian harus menentukan dalam keadaan apa setiap varian harus digunakan, yang tercakup dalam detail yang lebih besar di bagian Mengalokasikan varian .

Mendapatkan varian yang sesuai dengan konteks penargetan

Untuk setiap fitur, varian dapat diambil menggunakan metode dari FeatureManagergetVariant. Penetapan varian bergantung pada pengguna yang saat ini sedang dievaluasi, dan informasi tersebut diperoleh dari konteks penargetan yang Anda berikan. Jika Anda telah mendaftarkan aksesor konteks penargetan ke FeatureManager, konteks penargetan akan secara otomatis diambil darinya. Tetapi Anda masih dapat mengambil alihnya dengan meneruskan konteks penargetan secara manual saat memanggil getVariant.

const variant = await featureManager.getVariant("MyVariantFeatureFlag", { userId: "Sam" });

const variantName = variant.name;
const variantConfiguration = variant.configuration;

// Do something with the resulting variant and its configuration

Deklarasi penanda fitur variasi

Dibandingkan dengan bendera fitur normal, bendera fitur varian memiliki dua properti lagi: variants dan allocation. Properti variants adalah array yang berisi varian yang ditentukan untuk fitur ini. Properti allocation menentukan bagaimana varian ini harus dialokasikan untuk fitur tersebut. Sama seperti mendeklarasikan bendera fitur normal, Anda dapat menyiapkan bendera fitur varian dalam file JSON. Berikut adalah contoh bendera fitur varian.

{
    "feature_management": {
        "feature_flags": [
            {
                "id": "MyVariantFeatureFlag",
                "enabled": true,
                "allocation": {
                    "default_when_enabled": "Small",
                    "group": [
                        {
                            "variant": "Big",
                            "groups": [
                                "Ring1"
                            ]
                        }
                    ]
                },
                "variants": [
                    { 
                        "name": "Big"
                    },  
                    { 
                        "name": "Small"
                    } 
                ]
            }
        ]
    }
}

Menentukan varian

Setiap varian memiliki dua properti: nama dan konfigurasi. Nama ini digunakan untuk merujuk ke varian tertentu, dan konfigurasinya adalah nilai varian tersebut. Konfigurasi dapat diatur menggunakan configuration_value properti . configuration_value adalah konfigurasi sebaris yang dapat berupa string, angka, boolean, atau objek konfigurasi. Jika configuration_value tidak ditentukan, properti varian configuration yang dikembalikan adalah undefined.

Daftar semua variasi yang mungkin ditentukan untuk setiap fitur di bawah properti variants.

{
    "feature_management": {
        "feature_flags": [
            {
                "id": "MyVariantFeatureFlag",
                "variants": [
                    { 
                        "name": "Big", 
                        "configuration_value": {
                            "Size": 500
                        }
                    },  
                    { 
                        "name": "Small", 
                        "configuration_value": {
                            "Size": 300
                        }
                    } 
                ]
            }
        ]
    }
}

Mengalokasikan varian

Proses pengalokasian varian fitur ditentukan oleh allocation properti fitur.

"allocation": { 
    "default_when_disabled": "Small",  
    "default_when_enabled": "Small", 
    "user": [ 
        { 
            "variant": "Big", 
            "users": [ 
                "Marsha" 
            ] 
        } 
    ], 
    "group": [ 
        { 
            "variant": "Big", 
            "groups": [ 
                "Ring1" 
            ] 
        } 
    ],
    "percentile": [ 
        { 
            "variant": "Big", 
            "from": 0, 
            "to": 10 
        } 
    ], 
    "seed": "13973240" 
},
"variants": [
    { 
        "name": "Big", 
        "configuration_value": "500px"
    },  
    { 
        "name": "Small", 
        "configuration_value": "300px"
    } 
]

Pengaturan allocation fitur memiliki properti berikut:

Properti	Deskripsi
default_when_disabled	Menentukan varian mana yang harus digunakan ketika varian diminta sementara fitur dianggap dinonaktifkan.
default_when_enabled	Menentukan varian mana yang harus digunakan saat varian diminta saat fitur dianggap diaktifkan dan tidak ada varian lain yang ditetapkan kepada pengguna.
user	Menentukan varian dan daftar pengguna yang harus ditetapkan varian tersebut.
group	Menentukan varian dan daftar grup. Varian ditetapkan jika pengguna berada di setidaknya salah satu grup.
percentile	Menentukan varian dan rentang persentase yang harus sesuai dengan persentase yang dihitung pengguna agar varian tersebut ditetapkan.
seed	Nilai yang menjadi dasar perhitungan persentase untuk percentile. Perhitungan persentase untuk pengguna tertentu akan sama di semua fitur jika nilai yang sama seed digunakan. Jika tidak ada seed yang ditentukan, maka seed default dibuat berdasarkan nama fitur.

Jika fitur tidak diaktifkan, pengelola fitur menetapkan varian yang ditandai sebagai default_when_disabled kepada pengguna saat ini, yang dalam hal ini adalah Small.

Jika fitur diaktifkan, manajer fitur memeriksa alokasi user, group, dan percentile secara berurutan untuk menetapkan varian. Untuk contoh khusus ini, jika pengguna yang dievaluasi diberi nama Marsha, dalam grup bernama Ring1, atau pengguna kebetulan jatuh antara persentil ke-0 dan ke-10, maka varian yang ditentukan ditetapkan untuk pengguna. Dalam hal ini, semua pengguna yang ditugaskan akan memilih versi Big. Jika tidak ada alokasi ini yang cocok, pengguna diberi default_when_enabled varian, yaitu Small.

Logika alokasi mirip pada filter fitur Microsoft.Targeting, namun ada beberapa parameter yang ada dalam targeting yang tidak ada dalam alokasi, dan sebaliknya. Hasil penargetan dan alokasi tidak terkait.

Mengesampingkan status pengaktifan dengan variasi

Anda dapat menggunakan varian untuk mengambil alih status bendera fitur yang diaktifkan. Menggantikan memberi varian kesempatan untuk memperluas evaluasi flag fitur. Saat memanggil is_enabled pada bendera dengan varian, manajer fitur akan memeriksa apakah varian yang ditetapkan ke pengguna saat ini dikonfigurasi untuk menggantikan hasilnya. Penggantian dilakukan menggunakan properti varian opsional status_override. Secara default, properti ini diatur ke None, yang berarti varian tidak memengaruhi apakah bendera dianggap diaktifkan atau dinonaktifkan. Pengaturan status_override untuk Enabled memungkinkan varian, saat dipilih, untuk mengambil alih bendera yang akan diaktifkan. Pengaturan status_override untuk Disabled menyediakan fungsionalitas yang berlawanan, oleh karena itu menonaktifkan bendera saat varian dipilih. Fitur dengan status enabledfalse tidak dapat diubah.

Jika Anda menggunakan bendera fitur dengan varian biner, status_override properti dapat membantu. Ini memungkinkan Anda untuk terus menggunakan API seperti is_enabled dalam aplikasi Anda, sekaligus mendapat manfaat dari fitur baru yang dilengkapi dengan varian, seperti alokasi persentil dan benih.

{
    "id": "MyVariantFeatureFlag",
    "enabled": true,
    "allocation": {
        "percentile": [
            {
                "variant": "On",
                "from": 10,
                "to": 20
            }
        ],
        "default_when_enabled":  "Off",
        "seed": "Enhanced-Feature-Group"
    },
    "variants": [
        {
            "name": "On"
        },
        {
            "name": "Off",
            "status_override": "Disabled"
        }
    ]
}

Dalam contoh di atas, fitur selalu diaktifkan. Jika pengguna saat ini berada dalam rentang persentil terhitung 10 hingga 20, maka akan mengembalikan varian On. Jika tidak, Off varian dikembalikan dan karena status_override sama dengan Disabled, fitur sekarang akan dianggap dinonaktifkan.

telemetri

Ketika perubahan bendera fitur disebarkan, sering kali penting untuk menganalisis efeknya pada aplikasi. Misalnya, berikut adalah beberapa pertanyaan yang mungkin muncul:

• Apakah bendera saya diaktifkan/dinonaktifkan seperti yang diharapkan?
• Apakah pengguna yang ditargetkan mendapatkan akses ke fitur tertentu seperti yang diharapkan?
• Varian mana yang dilihat pengguna tertentu?

Jenis pertanyaan ini dapat dijawab melalui emisi dan analisis peristiwa evaluasi bendera fitur.

Mengaktifkan telemetri

Secara bawaan, bendera fitur tidak mengeluarkan telemetri. Untuk menerbitkan telemetri untuk bendera fitur tertentu, bendera HARUS menyatakan bahwa ia diaktifkan untuk pengiriman telemetri.

Untuk pengaturan fitur yang ditentukan dalam json, pengaktifan dilakukan dengan menggunakan properti telemetry.

{
    "feature_management": {
        "feature_flags": [
            {
                "id": "MyFeatureFlag",
                "enabled": true,
                "telemetry": {
                    "enabled": true
                }
            }
        ]
    }
}

Cuplikan di atas mendefinisikan bendera fitur bernama MyFeatureFlag yang diaktifkan untuk telemetri. Properti telemetry objek enabled diatur ke true. Nilai properti enabled harus true untuk menerbitkan telemetri untuk bendera.

Bagian telemetry bendera fitur memiliki properti berikut:

Properti	Deskripsi
enabled	Menentukan apakah telemetri untuk penanda fitur harus diterbitkan.
metadata	Kumpulan pasangan kunci-nilai, yang dimodelkan sebagai kamus, yang dapat digunakan untuk melampirkan metadata kustom tentang bendera fitur ke peristiwa evaluasi.

Penerbitan telemetri khusus

Anda dapat mendaftarkan fungsi panggilan balik onFeatureEvaluated saat membuat FeatureManager. Panggilan balik ini dipanggil setiap kali bendera fitur dievaluasi dan telemetri diaktifkan untuk bendera tersebut. Fungsi panggilan balik akan mengambil hasil evaluasi fitur sebagai parameter .

Contoh berikut menunjukkan cara menerapkan fungsi panggilan balik kustom untuk mengirim telemetri dengan informasi yang diekstrak dari hasil evaluasi fitur dan mendaftarkannya ke manajer fitur.

const sendTelemetry = (evaluationResult) => {
    const featureId = evaluationResult.feature.id;
    const featureEnabled = evaluationResult.enabled;
    const targetingId = evaluationResult.targetingId;
    const variantName = evaluationResult.variant?.name;
    const variantAssignmentReason = evaluationResult.variantAssignmentReason;
    // custom code to send the telemetry
    // ...
}
const featureManager = new FeatureManager(featureProvider, { onFeatureEvaluated :  sendTelemtry});

Integrasi Application Insights

Pustaka manajemen fitur JavaScript menyediakan paket ekstensi yang terintegrasi dengan SDK Application Insights .

Application Insights menawarkan SDK yang berbeda untuk skenario web dan Node.js . Silakan pilih paket ekstensi yang benar untuk aplikasi Anda.

Peramban

Jika aplikasi Anda berjalan di browser, instal "@microsoft/feature-management-applicationinsights-browser" paket. Contoh berikut menunjukkan bagaimana Anda dapat membuat penerbit telemetri Application Insights bawaan dan mendaftarkannya ke pengelola fitur.

import { ApplicationInsights } from "@microsoft/applicationinsights-web"
import { FeatureManager, ConfigurationObjectFeatureFlagProvider } from "@microsoft/feature-management";
import { createTelemetryPublisher, trackEvent } from "@microsoft/feature-management-applicationinsights-browser";

const appInsights = new ApplicationInsights({ config: {
    connectionString: "<APPINSIGHTS_CONNECTION_STRING>"
}});
appInsights.loadAppInsights();

const publishTelemetry = createTelemetryPublisher(appInsights);
const provider = new ConfigurationObjectFeatureFlagProvider(jsonObject);
const featureManager = new FeatureManager(provider, {onFeatureEvaluated: publishTelemetry});

// FeatureEvaluation event will be emitted when a feature flag is evaluated
featureManager.getVariant("TestFeature", {userId : TARGETING_ID}).then((variant) => { /* do something*/ });

// Emit a custom event with targeting id attached.
trackEvent(appInsights, TARGETING_ID, {name: "TestEvent"}, {"Tag": "Some Value"});

Node.js

Jika aplikasi Anda berjalan di Node.js, instal "@microsoft/feature-management-applicationinsights-node" paket. Contoh berikut menunjukkan bagaimana Anda dapat membuat penerbit telemetri Application Insights bawaan dan mendaftarkannya ke pengelola fitur.

const appInsights = require("applicationinsights");
appInsights.setup(process.env.APPINSIGHTS_CONNECTION_STRING).start();

const { FeatureManager, ConfigurationObjectFeatureFlagProvider } = require("@microsoft/feature-management");
const { createTelemetryPublisher, trackEvent } = require("@microsoft/feature-management-applicationinsights-node");

const publishTelemetry = createTelemetryPublisher(appInsights.defaultClient);
const provider = new ConfigurationObjectFeatureFlagProvider(jsonObject);
const featureManager = new FeatureManager(provider, {onFeatureEvaluated: publishTelemetry});

// FeatureEvaluation event will be emitted when a feature flag is evaluated
featureManager.getVariant("TestFeature", {userId : "<TARGETING_ID>"}).then((variant) => { /* do something*/ });

// Emit a custom event with targeting id attached.
trackEvent(appInsights.defaultClient, "<TARGETING_ID>", {name: "TestEvent",  properties: {"Tag": "Some Value"}});

Penerbit telemetri mengirimkan FeatureEvaluation peristiwa kustom ke Application Insights ketika bendera fitur yang diaktifkan untuk telemetri dievaluasi. Peristiwa kustom mengikuti skema FeatureEvaluationEvent .

Menargetkan prosesor telemetri

Jika Anda telah menerapkan ITargetingContextAccessor, Anda dapat menggunakan prosesor telemetri bawaan Application Insights untuk melampirkan informasi ID penargetan secara otomatis ke semua telemetri dengan memanggil fungsi createTargetingTelemetryProcessor.

const appInsights = require("applicationinsights");
appInsights.setup(process.env.APPINSIGHTS_CONNECTION_STRING).start();

const { createTargetingTelemetryProcessor } = require("@microsoft/feature-management-applicationinsights-node");
appInsights.defaultClient.addTelemetryProcessor(
    createTargetingTelemetryProcessor(targetingContextAccessor)
);

Ini memastikan bahwa setiap item telemetri yang dikirim ke Application Insights menyertakan informasi ID penargetan pengguna (userId dan grup), memungkinkan Anda menghubungkan penggunaan bendera fitur dengan pengguna atau grup tertentu dalam analitik Anda.

Jika Anda menggunakan prosesor telemetri penargetan, daripada memanggil metode trackEvent yang disediakan oleh paket manajemen fitur, Anda dapat langsung memanggil metode trackEvent dari Application Insights SDK. Informasi ID penargetan akan secara otomatis dilampirkan ke telemetri customDimensionsperistiwa kustom.

// Instead of calling trackEvent and passing the app insights client
// trackEvent(appInsights.defaultClient, "<TARGETING_ID>", {name: "TestEvent",  properties: {"Tag": "Some Value"}});

// directly call trackEvent method provided by App Insights SDK
appInsights.defaultClient.trackEvent({ name: "TestEvent" });

Langkah berikutnya

Untuk mempelajari cara menggunakan flag fitur di aplikasi Anda, lanjutkan ke panduan cepat berikut.

Ular sawah

Untuk mempelajari cara menggunakan filter fitur, lanjutkan ke tutorial berikut.

Mengaktifkan fitur bersyarat dengan filter fitur

Mengaktifkan fitur sesuai jadwal

Meluncurkan fitur ke audiens yang ditargetkan