링크 첨부파일을 클래스룸 부가기능 첨부파일로 업그레이드하기

교사가 클래스룸에 서드 파티 콘텐츠를 추가하는 한 가지 방법은 과제 만들기 페이지에 링크를 링크 첨부파일로 붙여넣는 것입니다. 이제 교사들이 이미 익숙한 기능을 활용하여 교사가 링크 첨부파일을 부가기능 첨부파일로 업그레이드할 수 있도록 부가기능을 구성할 수 있습니다.

개요

이 기능을 사용하여 부가기능을 구성하면 교사가 과제 생성 페이지에 링크 첨부파일을 붙여넣을 때 부가기능 첨부파일의 링크를 업그레이드하라는 메시지가 표시됩니다. 교사는 이미 부가기능을 설치한 경우에만 이를 사용하라는 메시지가 표시됩니다.

교사가 링크를 부가기능 첨부파일로 업그레이드하는 데 동의하면 다음 쿼리 매개변수를 사용하여 링크 업그레이드 iframe이 실행됩니다.

courseId
itemId
itemType
addOnToken
urlToUpgrade
login_hint (사용자가 이미 앱을 승인한 경우만)

처음 4개의 쿼리 매개변수는 첨부파일 검색 iframe에서 실행된 쿼리 매개변수를 미러링합니다. 새로 추가된 urlToUpgrade 쿼리 매개변수는 부가기능 첨부파일을 만드는 방법을 평가하는 데 도움이 됩니다. 그런 다음 다른 쿼리 매개변수를 사용하여 사용자가 로그인했는지 확인하고 itemType 값에 따라 courseWork, courseWorkMaterials 또는 announcements의 CreateAddOnAttachment 메서드를 호출할 수 있습니다. iframe 내에서 로드 화면을 표시하여 교사에게 부가기능 첨부파일이 생성 중임을 알릴 수 있습니다.

부가기능 첨부파일이 생성되면 iframe이 닫히고 교사는 평소와 같이 과제에서 첨부파일을 볼 수 있습니다.

기술 구현 세부정보

이 섹션에서는 이 기능에 대한 몇 가지 중요한 기술적 세부정보를 중점적으로 설명합니다.

`urlToUpgrade` 쿼리 매개변수 읽기

urlToUpgrade 쿼리 매개변수는 링크 업그레이드 iframe에서 전달될 때 URI로 인코딩됩니다. URL을 원래 형태로 가져오려면 디코딩해야 합니다. 예를 들어 JavaScript를 사용하는 경우 decodeURIComponent() 함수를 사용하면 됩니다.

링크 업그레이드 iframe 닫기

이 기능에 대한 최적의 사용자 환경을 제공하려면 부가기능 첨부파일이 성공적으로 생성된 후 postMessage를 전송합니다. 이렇게 하면 iframe이 닫힙니다. 자세한 내용은 iframe 구현 세부정보 페이지를 참고하세요.

구성 세부정보

이 기능을 부가기능에 통합하려면 다음 구성이 필요합니다.

링크 업그레이드 iframe URL: 교사가 업그레이드에 동의하면 iframe에서 열리는 URL입니다.
클래스룸에서 감지하고 업그레이드를 시도해야 하는 URL 패턴: URL 패턴은 호스트 및 여러 경로 프리픽스로 구성될 수 있습니다.
- 여러 URL 패턴을 제공할 수 있습니다.
- 경로 프리픽스를 제공하지 않으면 호스트와 일치하는 모든 URL을 업그레이드할 수 있습니다.
- https 스키마를 사용하는 URL만 업그레이드할 수 있습니다.
- URL 패턴은 localhost를 포함할 수 없습니다.
- 경로 프리픽스에는 쿼리 매개변수 또는 URL 프래그먼트가 포함되면 안 됩니다.
- 현재 경로 프리픽스는 다음과 같은 와일드 카드를 지원할 수 있지만 호스트는 지원하지 않습니다.
  - example.com는 유효한 호스트이고 /foo 및 /bar/*/baz는 유효한 경로 프리픽스입니다.
  - example.*.host.com은(는) 유효한 호스트가 아닙니다.
- 경로 접두어 구성요소 사이의 와일드 카드는 단일 구성요소와만 일치하며 슬래시로 구분된 여러 구성요소와는 일치하지 않습니다. 호스트 example.com 및 경로 프리픽스 /bar/*/baz가 있는 URL 패턴을 고려하세요.
  - https://example.com/bar/123/baz는 URL 패턴과의 유효한 일치 항목입니다.
  - https://example.com/bar/123/baz/456/789는 URL 패턴과의 유효한 일치 항목입니다.
  - 경로 프리픽스의 와일드 카드가 /123/456/와 일치하지 않으므로 https://example.com/bar/123/456/baz는 URL 패턴과의 유효한 일치 항목이 아닙니다.

개발 프로세스

classroom-link-upgrade-external@google.com으로 이메일을 보내 테스트 또는 프로덕션 부가기능의 링크 업그레이드 iframe URL 및 URL 패턴을 전송합니다.

먼저 비공개 부가기능과 소유하고 있는 테스트 또는 개발 환경의 구성을 제공할 수 있습니다. 데모 도메인에서 흐름을 테스트할 수 있도록 프로덕션 구성을 사용 설정하기 전에 클래스룸팀이 이러한 테스트 구성을 사용 설정할 수 있습니다. 구성이 사용 설정되면 이메일 답장이 전송됩니다. localhost를 사용하는 URL 패턴은 이 기능에 지원되지 않습니다.

다음을 포함하도록 이메일 형식을 지정합니다.

Google Cloud Project number: GCP_PROJECT_NUMBER

Link Upgrade iframe URL: LINK_UPGRADE_IFRAME_URL

URL Patterns:
- Host:HOST_1
- Path prefixes:
  - PATH_PREFIX_1
  - PATH_PREFIX_2

- Host:HOST_2
- Path prefixes:
  - PATH_PREFIX_3
  - PATH_PREFIX_4

// add more hosts and path prefixes as needed

다음을 바꿉니다.

GCP_PROJECT_NUMBER: 부가기능이 연결된 Google Cloud 프로젝트의 번호입니다.
LINK_UPGRADE_IFRAME_URL 링크 업그레이드 iframe에서 열리는 URL을 지정합니다.
HOST_1: 클래스룸에서 감지해야 하는 호스트입니다. https 스키마만 지원됩니다.
PATH_PREFIX_1 및 PATH_PREFIX_2: 클래스룸에서 감지하여 업그레이드를 시도해야 하는 HOST_1과 연결된 경로 프리픽스입니다.
HOST_2: 클래스룸에서 감지해야 하는 호스트입니다. https 스키마만 지원됩니다.
PATH_PREFIX_3 및 PATH_PREFIX_4: 클래스룸에서 감지하여 업그레이드를 시도해야 하는 HOST_2와 연결된 경로 프리픽스입니다.

권장 사용자 환경

다음은 이 기능을 구현할 때 고려해야 할 제안사항입니다.

교사의 추가 작업 방지

필요한 경우 로그인을 용이하게 하거나 로드 표시기를 표시할 수 있도록 iframe을 사용하는 것이 좋습니다. 최상의 사용자 환경을 위해 붙여넣은 링크를 부가기능 첨부파일로 업그레이드하는 데 동의한 후에는 교사에게 추가 정보를 입력하라는 메시지가 표시되지 않아야 합니다. 하지만 부가기능에서 이 방법을 사용할 수 없는 경우 링크 업그레이드 iframe을 사용하여 필요한 추가 정보를 수집할 수 있습니다. iframe을 사용하여 링크를 업그레이드할 수 없거나 오류가 발생한 경우 교사에게 알릴 수도 있습니다.

사용자 친화적인 액세스 오류 메시지 포함

교사가 액세스 권한이 없는 링크를 붙여넣고 업그레이드하는 경우 교사가 문제를 알 수 있도록 iframe에 사용자 친화적인 오류 메시지를 표시합니다. iframe을 사용하여 교사에게 콘텐츠에 액세스할 수 있는 적절한 권한을 제공할 수도 있습니다.