교사가 클래스룸에 서드 파티 콘텐츠를 추가하는 한 가지 방법은 과제 만들기 페이지에 링크를 링크 첨부파일로 붙여넣는 것입니다. 교사에게 이미 익숙한 기능을 사용하려면 이제 교사가 링크 첨부파일을 부가기능 첨부파일로 업그레이드할 수 있도록 부가기능을 구성할 수 있습니다.
개요
이 기능으로 부가기능을 구성하는 경우 교사가 과제 만들기 페이지에 링크 연결을 붙여넣을 때 링크를 부가기능 첨부파일로 업그레이드하라는 메시지가 표시됩니다. 교사에게 이미 부가기능을 설치한 경우에만 설치하라는 메시지가 표시됩니다.
교사가 링크를 부가기능 첨부파일로 업그레이드하는 데 동의하면 다음 쿼리 매개변수와 함께 링크 업그레이드 iframe이 실행됩니다.
courseId
itemId
(postId
에서 이름 바꾸기)itemType
(신규!)addOnToken
login_hint
또는hd
urlToUpgrade
(신규!)
처음 4개의 쿼리 매개변수는 첨부파일 검색 iframe에서 실행된 쿼리 매개변수를 미러링합니다. urlToUpgrade
쿼리 매개변수는 새로운 매개변수이며 부가기능 연결을 어떻게 만들어야 하는지 평가하는 데 도움이 됩니다. 그런 다음 다른 쿼리 매개변수를 사용하여 사용자가 로그인했는지 확인하고 itemType
값에 따라 courseWork
, courseWorkMaterials
또는 announcements
의 CreateAddOnAttachment
메서드를 호출할 수 있습니다. iframe 내에서 로드 화면을 표시하여 교사에게 부가기능 첨부파일이 만들어지고 있음을 나타낼 수 있습니다.
부가기능 첨부파일이 생성되면 iframe이 닫히고 교사는 평소와 같이 과제에서 첨부파일을 볼 수 있습니다.
기술 구현 세부정보
이 섹션에서는 기능에 대한 몇 가지 중요한 기술 세부정보를 중점적으로 설명합니다.
urlToUpgrade
쿼리 매개변수 읽기
urlToUpgrade
쿼리 매개변수는 링크 업그레이드 iframe을 통해 전달될 때 URI 인코딩됩니다. URL을 디코딩하여 원래 형식으로 가져와야 합니다. 예를 들어 자바스크립트를 사용하는 경우 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을 사용하여 교사에게 콘텐츠에 액세스할 수 있는 적절한 권한을 제공할 수도 있습니다.