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

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

개요

이 기능으로 부가기능을 구성하면 교사가 과제 만들기 페이지에 링크 첨부파일을 붙여넣을 때 링크를 부가기능 첨부파일로 업그레이드하라는 메시지가 표시됩니다. 교사에게 부가기능 설치 메시지가 표시되는 경우는 이미 부가기능이 설치된 경우에만 해당합니다.

교사가 부가기능 첨부파일로 링크를 업그레이드하는 데 동의하면 다음 쿼리 매개변수를 사용하여 링크 업그레이드 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 패턴을 전송합니다.

클래스룸 부가기능을 나타내는 모든 Google Cloud 프로젝트에 구성을 제공할 수 있습니다. 실시간 사용자에게 영향을 주지 않고 데모 도메인에서 개발하고 테스트할 수 있도록 먼저 비공개 공개 상태의 부가기능 구성을 제공하는 것이 좋습니다.

구성이 사용 설정되면 이메일 응답이 전송됩니다. 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은 교사에게 콘텐츠에 액세스할 수 있는 적절한 권한을 제공하는 데도 사용할 수 있습니다.