同意字符串编码器/解码器

同意字符串将用户同意状态存储为二进制数据,编码为base64. 将用户同意状态编码为二进制字符串,或从已存在的字符串中解码,都需要一个编码器/解码器库.

库支持定义于 @didomi/consent-string-schema 图书馆.

Ưμ㼯A 这里

Didomi 同意字符串

Didomi 的同意字符串格式在以下文件中描述 :

• DCS v1 (英语) 杜米 - 同意弦 - 司马 - v1.json
• DCS v2 (英语) 杜米 - 同意弦 - 司马 - v2.json

编码

我们在用图书馆 encodeDCS 功能将用户状态编码到 DCS :

import { encodeDCS } from '@didomi/consent-string';

const consentString = encodeDCS(1, {
  userId: 'd113bb93-7aa3-4684-ab31-aa9ae45470cb',
  created: new Date('2024-01-01'),
  updated: new Date('2024-01-01'),
  vendors: {
    optin: {
      enabled: [],
      disabled: [],
    },
    optout: {
      enabled: [],
      disabled: [],
    },
  },
  purposes: {
    optin: {
      enabled: [],
      disabled: [],
    },
    optout: {
      enabled: [],
      disabled: [],
    },
  },
  sync: null,
});

这个 encodeDCS 接受下列参数:

• version - 那个 number 要使用的DCS 版本
• userStatus - 用户状态 object 编码
• options - 选项 object 用于编码 DCS

可选 options 对象提供 SchemaOverrides 特性

/**
 * Options for encoding a DCS
 */
export type EncodeDCSOptions = {
  /**
   * Overrides applied to the schema
   */
  schemaOverrides?: SchemaOverrides;
};

使用 SchemaOverrides 我们可以限制方案只使用选定的编码算法,例如:

const userStatus = {
  userId: 'd113bb93-7aa3-4684-ab31-aa9ae45470cb',
  created: new Date('2024-01-01'),
  updated: new Date('2024-01-01'),
  regulationId: 10,
  purposes: {
    optin: {
      enabled: [1, 100],
      disabled: [],
    },
    optout: {
      enabled: [],
      disabled: [],
    },
  },
  vendors: {
    optin: {
      enabled: [],
      disabled: [],
    },
    optout: {
      enabled: [],
      disabled: [],
    },
  },
  sync: null,
};

const consentStringWithVariantRestrictions = encodeDCS(2, userStatus, {
  schemaOverrides: {
    fields: {
      purposes_optin: {
        variants: [EncodingAlgorithm.BIT_FIELD_2_BITS],
      },
    },
  },
});

在这种情况下 consentStringWithVariantRestrictions 应使用比特字段编码 purposes_optin 财务报告和审定财务报表 生成的结果与DCS v1 编码相同.

有一个 EncodingAlgorithm 支持的选项

export enum EncodingAlgorithm {
  BIT_FIELD_2_BITS = 'bit_field_2_bits',
  RANGES_FIBONACCI = 'ranges_fibonacci',
  RANGES_U16 = 'ranges_u16',
}

解码

要解码DCS字符串我们需要使用 decodeDCS 函数

import { decodeDCS } from '@didomi/consent-string';

const consentString =
  'BGHWv4UYba5-dZnABdKu__D6iWHsD6iWHsJ9iee2BAAilKiABFKVQAACIscAAAiLGAAA';
const expectedUserStatus = {
  user_id: '1875afe1-461b-6b9f-9d66-700174abbffc',
  created: '2023-04-12T18:10:00.000Z',
  updated: '2023-04-12T18:10:00.000Z',
  sync: '2023-05-24T18:10:00.000Z',
  vendors_optin: {
    enabled: [128, 129, 130, 131, 132],
    disabled: [],
  },
  purposes_optin: {
    enabled: [1, 2, 6, 7, 8],
    disabled: [3, 4],
  },
  vendors_optout: {
    enabled: [128, 129, 130, 131, 132],
    disabled: [],
  },
  purposes_optout: {
    enabled: [1, 2, 6, 7, 8],
    disabled: [3, 4],
  },
};
expect(decodeDCS(consentString)).toEqual(expectedUserStatus);

这个 decodeDCS 接受此选项 consentString 作为参数并返回用户状态对象.

解码日志

在某些情况下,我们需要知道用来生产DCS字符串的编码算法. 这个 logs 选项提供了收集编码器信息的途径:

有伐木的例子:

import { decodeDCS } from '@didomi/consent-string';

const consentString =
  'CGHWv4UYba5-dZnABdKu__D6iWHsD6iWHsAAKn2J57YEACKUqIAEUpVAAAIixwAACIsY';
const expectedEntries: LogEntry[] = [
  {
    key: 'version',
    offset: 0,
    usedEncoder: 'u6',
  },
  {
    key: 'user_id',
    offset: 6,
    usedEncoder: 'UUID',
  },
  {
    key: 'created',
    offset: 134,
    usedEncoder: 'date',
  },
  {
    key: 'updated',
    offset: 170,
    usedEncoder: 'date',
  },
  {
    key: 'regulation_id',
    offset: 206,
    usedEncoder: 'u16',
  },
  {
    key: 'sync',
    offset: 222,
    usedEncoder: 'date',
  },
  {
    key: 'purposes_optin',
    offset: 259,
    usedEncoder: 'bitField2Bits',
  },
  {
    key: 'purposes_optout',
    offset: 294,
    usedEncoder: 'bitField2Bits',
  },
  {
    key: 'vendors_optin',
    offset: 329,
    usedEncoder: 'rangesFibonacci',
  },
  {
    key: 'vendors_optout',
    offset: 367,
    usedEncoder: 'rangesFibonacci',
  },
];
const entries: LogEntry[] = [];
const logs: Logs = { enabled: true, entries };
decodeDCS(consentString, { logs });
expect(entries).toEqual(expectedEntries);