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

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

개요

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

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

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

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

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

기술 구현 세부정보

이 섹션에서는 기능의 중요한 기술 세부정보를 강조합니다.

`urlToUpgrade` 쿼리 매개변수 읽기

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

링크 업그레이드 iframe 닫기

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

구성 세부정보

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

링크 업그레이드 iframe URL: 교사가 업그레이드에 동의하면 iframe에서 열리는 URL입니다.
Classroom에서 감지하고 업그레이드를 시도해야 하는 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 패턴과 일치합니다.
  - https://example.com/bar/123/456/baz은 경로 접두사의 와일드 카드가 /123/456/와 일치하지 않으므로 URL 패턴과 일치하지 않습니다.

개발 프로세스

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

Classroom 부가기능을 나타내는 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을 사용하여 교사에게 콘텐츠에 액세스할 수 있는 적절한 권한을 제공할 수도 있습니다.