확장 매니페스트

확장의 기본 디렉터리에 이름이 extension.json인 파일을 생성해야 합니다. 여기에는 Adobe Experience Platform에서 확장을 적절하게 사용할 수 있도록 하는 중요한 세부 정보가 포함되어 있습니다. 일부 컨텐츠는 npm의 package.json 방식을 따라 형성됩니다.

예제 extension.json은 Hello World 확장 GitHub 리포지토리에서 찾을 수 있습니다.

확장 매니페스트는 다음과 같이 구성되어야 합니다.

부록

명명 규칙

extension.json에서 모든 name 필드의 값은 다음 규칙을 준수해야 합니다.

• 214자 이하여야 합니다.
• 점 또는 밑줄로 시작할 수 없습니다.
• 대문자를 포함하지 않아야 합니다.
• URL 안전 문자만 포함해야 합니다.

이는 npm 패키지 이름 규칙과 일치합니다.

구성 객체 속성

구성 객체는 다음과 같이 구조화해야 합니다.

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "delay": {
      "type": "number",
      "minimum": 1
    }
  },
  "required": [
    "delay"
  ],
  "additionalProperties": false
}

유형 정의

유형 정의는 이벤트, 조건, 작업 또는 데이터 요소 유형을 설명하는 데 사용되는 객체입니다. 객체는 다음과 같이 구성됩니다.

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "delay": {
      "type": "number",
      "minimum": 1
    }
  },
  "required": [
    "delay"
  ],
  "additionalProperties": false
}

변형

특정 사용 사례의 경우, 확장은 태그 런타임 라이브러리로 내보내기 전에 뷰에서 저장한 설정 객체를 Platform으로 변환해야 합니다. extension.json 내에서 유형 정의를 정의할 때 transforms 속성을 설정하여 이러한 변형 중 하나 이상을 수행하도록 요청할 수 있습니다. transforms 속성은 각 객체가 수행해야 하는 변형을 나타내는 객체의 배열입니다.

모든 변환에서는 type 및 propertyPath가 필요합니다. 다음 type 은(는) 다음 중 하나여야 합니다. function, remove, 및 file 및 에서는 Platform이 설정 객체에 적용할 변형에 대해 설명합니다. 다음 propertyPath 는 설정 객체에서 수정해야 하는 속성을 찾을 위치를 태그에 알려주는 마침표로 구분되는 문자열입니다. 다음은 설정 객체 및 일부 propertyPath의 예입니다.

{
  foo: {
    bar: "A string",
    baz: [
      "A",
      "B",
      "C"
    ]
  }
}

• foo.bar의 propertyPath를 설정하면 "A string" 값이 변형됩니다.
• foo.baz[]의 propertyPath를 설정하면 baz 배열의 각 값이 변형됩니다.
• foo.baz의 propertyPath를 설정하면 baz 배열이 변형됩니다.

속성 경로는 배열과 객체 표기법의 조합을 사용하여 설정 객체의 모든 수준에서 변형을 적용할 수 있습니다.

아래 섹션에서는 사용 가능한 변형과 변형을 사용하는 방법에 대해 설명합니다.

함수 변형

함수 변형을 사용하면 Platform 사용자가 작성한 코드를 내보낸 태그 런타임 라이브러리 내의 라이브러리 모듈에서 실행할 수 있습니다.

사용자 정의 스크립트 작업 유형을 제공한다고 가정해 보겠습니다. 사용자 정의 스크립트 작업 보기는 사용자가 일부 코드를 입력할 수 있는 텍스트 영역을 제공할 수 있습니다. 사용자가 텍스트 영역에 다음 코드를 입력했다고 가정해 보겠습니다.

console.log('Welcome, ' + username +'. This is ZomboCom.');

사용자가 규칙을 저장할 때, 보기에 의해 저장된 설정 객체는 다음과 같이 표시될 수 있습니다.

{
  foo: {
    bar: "console.log('Welcome, ' + username +'. This is ZomboCom.');"
  }
}

작업을 사용하는 규칙이 태그 런타임 라이브러리 내에서 실행될 때 사용자의 코드를 실행하고 사용자 이름을 전달합니다.

설정 객체가 작업 유형의 보기에서 저장될 때 사용자의 코드는 단순한 문자열입니다. 이는 JSON에서 제공되고 올바르게 직렬화할 수 있으므로 좋습니다. 하지만 일반적으로 실행 가능한 함수 대신 문자열로 태그 런타임 라이브러리에서 내보내지기 때문에 나쁜 점도 있습니다. 작업 유형의 라이브러리 모듈 내에서 eval 또는 함수 생성자를 사용하여 코드 실행을 시도할 수 있지만 컨텐츠 보안 정책으로 인해 실행이 차단될 수 있습니다.

이러한 상황에 대한 해결 방법으로, 함수 변형을 사용하면 태그 런타임 라이브러리에서 내보낼 때 Platform에 실행 가능한 함수에서 사용자 코드를 래핑하라고 알립니다. 예제 문제를 해결하기 위해 다음과 같이 extension.json의 유형 정의에 변형을 정의합니다.

{
  "transforms": [
    {
      "type": "function",
      "propertyPath": "foo.bar",
      "parameters": ["username"]
    }
  ]
}

• type은 설정 객체에 적용할 변형의 유형을 정의합니다.
• propertyPath 는 설정 객체에서 수정해야 하는 속성을 찾을 위치를 플랫폼에 알려주는 마침표로 구분되는 문자열입니다.
• parameters는 래핑 함수의 서명에 포함되어야 하는 매개 변수 이름의 배열입니다.

설정 객체가 태그 런타임 라이브러리에 전송되면 다음과 같이 변환됩니다.

{
  foo: {
    bar: function(username) {
      console.log('Welcome, ' + username +'. This is ZomboCom.');
    }
  }
}

라이브러리 모듈은 사용자 코드가 포함된 함수를 호출하고 username 인수를 전달할 수 있습니다.

파일 변형

파일 변형을 사용하면 Platform 사용자가 작성한 코드를 태그 런타임 라이브러리와 별도의 파일로 내보낼 수 있습니다. 파일은 태그 런타임 라이브러리와 함께 호스팅되며 런타임 시 확장에 필요에 따라 로드할 수 있습니다.

사용자 정의 스크립트 작업 유형을 제공한다고 가정해 보겠습니다. 작업 유형의 보기에서는 사용자가 일부 코드를 입력할 수 있는 텍스트 영역을 제공할 수 있습니다. 사용자가 텍스트 영역에 다음 코드를 입력했다고 가정해 보겠습니다.

console.log('This is ZomboCom.');

사용자가 규칙을 저장할 때, 보기에 의해 저장된 설정 객체는 다음과 같이 표시될 수 있습니다.

{
  foo: {
    bar: "console.log('This is ZomboCom.');"
  }
}

사용자 코드를 태그 런타임 라이브러리에 포함되지 않고 별도의 파일에 삽입하려고 합니다. 작업을 사용하는 규칙이 태그 런타임 라이브러리 내에서 실행될 때 문서 본문에 스크립트 요소를 추가하여 사용자의 코드를 로드하려고 합니다. 예제 문제를 해결하기 위해 다음과 같이 extension.json의 작업 유형 정의에 변형을 정의합니다.

{
  "transforms": [
    {
      "type": "file",
      "propertyPath": "foo.bar"
    }
  ]
}

• type은 설정 객체에 적용할 변형의 유형을 정의합니다.
• propertyPath 는 설정 객체에서 수정해야 하는 속성을 찾을 위치를 플랫폼에 알려주는 마침표로 구분되는 문자열입니다.

설정 객체가 태그 런타임 라이브러리에 전송되면 다음과 같이 변환됩니다.

{
  foo: {
    bar: "//launch.cdn.com/path/abc.js"
  }
}

이 경우 foo.bar의 값이 URL로 변형되었습니다. 정확한 URL은 라이브러리가 빌드될 때 결정됩니다. 파일에는 항상 .js 확장자가 지정되며 JavaScript 기반 MIME 유형을 사용하여 배달됩니다. 나중에 다른 MIME 유형에 대한 지원을 추가할 수 있습니다.

변형 제거

기본적으로 설정 객체의 모든 속성은 태그 런타임 라이브러리에 표시됩니다. 특정 속성이 확장 보기에만 사용되는 경우, 특히 중요한 정보(예: 비밀 토큰), 정보가 태그 런타임 라이브러리로 전송되지 않도록 하려면 변환 제거를 사용해야 합니다.

새로운 작업 유형을 제공한다고 가정해 보겠습니다. 작업 유형의 보기에서는 사용자가 특정 API에 대한 연결을 허용하는 비밀 키를 입력할 수 있는 입력을 제공할 수 있습니다. 사용자가 입력에 다음 텍스트를 입력했다고 가정해 보겠습니다.

ABCDEFG

사용자가 규칙을 저장할 때, 보기에 의해 저장된 설정 객체는 다음과 같이 표시될 수 있습니다.

{
  foo: {
    bar: "ABCDEFG"
  }
}

우리는 그 재산을 포함하지 않기를 원합니다 bar 를 입력합니다. 예제 문제를 해결하기 위해 다음과 같이 extension.json의 작업 유형 정의에 변형을 정의합니다.

{
  "transforms": [
    {
      "type": "remove",
      "propertyPath": "foo.bar"
    }
  ]
}

• type은 설정 객체에 적용할 변형의 유형을 정의합니다.
• propertyPath 는 설정 객체에서 수정해야 하는 속성을 찾을 위치를 플랫폼에 알려주는 마침표로 구분되는 문자열입니다.

설정 객체가 태그 런타임 라이브러리에 전송되면 다음과 같이 변환됩니다.

{
  foo: {
  }
}

이 경우 foo.bar의 값이 설정 객체에서 제거되었습니다.