iframe 및 쿼리 매개변수 세부정보

클래스룸 부가기능은 iframe 내에 로드되어 최종 사용자에게 원활하고 편리한 사용자 환경을 제공합니다. iframe 유형에는 네 가지가 있습니다. 각 iframe의 목적과 모양을 간략히 살펴보려면 사용자 여정 디렉터리의 iframe 페이지를 참고하세요.

iframe 보안 가이드라인

파트너는 업계 권장사항에 따라 iframe을 보호해야 합니다. iframe을 보호하려면 Google 보안팀에서 다음을 권장합니다.

• HTTPS가 필요합니다. TLS 1.2 이상을 사용하고 HTTP Strict Transport Security를 사용 설정하는 것이 좋습니다. Strict Transport Security에 관한 관련 MDN 도움말을 참고하세요.

• 엄격한 콘텐츠 보안 정책을 사용 설정합니다. 이 OWASP 도움말 및 관련 콘텐츠 보안 정책 MDN 도움말을 참고하세요.

• 보안 쿠키 속성을 사용 설정합니다. HttpOnly 속성 및 관련 쿠키 MDN 도움말을 참고하세요.

iFrame URI 구성

첨부파일 설정 URI는 첨부파일 검색 iframe이 로드되는 위치이며, 교사가 클래스룸 게시물에 부가기능 첨부파일을 만드는 흐름을 시작하는 위치입니다. Google Cloud 프로젝트 콘솔에서 설정할 수 있습니다. Google Cloud 프로젝트의 API 및 서비스 > Google Workspace Marketplace SDK > 앱 구성 페이지에서 이 URI를 설정합니다.

허용된 첨부파일 URI 접두사는 *.addOnAttachments.create 및 *.addOnAttachments.patch 메서드를 사용하여 AddOnAttachment에 설정된 URI를 검증하는 데 사용됩니다. 검증은 리터럴 문자열 접두사 일치이며 현재 와일드 카드를 사용할 수 없습니다.

쿼리 매개변수

iframe은 중요한 정보를 부가기능에 쿼리 매개변수로 전달합니다. 매개변수에는 첨부파일 관련 매개변수와 로그인 관련 매개변수라는 두 가지 카테고리가 있습니다.

첨부파일 관련 매개변수

첨부파일 관련 매개변수는 학습과정, 과제, 부가기능 첨부파일, 학생의 제출물, 승인 토큰에 관한 정보를 부가기능에 제공합니다.

과정 ID

courseId 값은 과정의 식별자입니다.

모든 iframe에 포함됩니다.

상품 ID

itemId 값은 Announcement의 식별자입니다.

이 연결이 연결된 CourseWork 또는 CourseWorkMaterial입니다.

모든 iframe에 포함됩니다.

항목 유형

itemType 값은 이 필드가 실행되는 리소스 유형을 식별합니다.

첨부파일이 첨부되었습니다. 전달된 문자열 값은 "announcements", "courseWork", "courseWorkMaterials" 중 하나입니다.

모든 iframe에 포함됩니다.

첨부파일 ID

attachmentId 값은 첨부파일의 식별자입니다.

teacherViewUri, studentViewUri, studentWorkReviewUri iframe에 포함됩니다.

제출물 ID

submissionId 값은 학생의 작업을 식별하는 식별자이지만 특정 과제의 학생 작업을 식별하려면 attachmentId와 함께 사용해야 합니다.

studentWorkReviewUri에 포함되어 있습니다.

부가기능 토큰

addOnToken 값은

addOnAttachments.create 호출을 통해 부가기능을 만듭니다.

첨부파일 검색 iframe 및 링크 업그레이드 iframe에 포함되어 있습니다.

업그레이드할 URL

urlToUpgrade 값이 있으면

교사가 과제에 링크 첨부파일을 포함했으며 부가기능 첨부파일로 업그레이드하기로 동의했습니다. 이 기능을 아직 구성하지 않은 경우 부가기능 첨부파일 링크 업그레이드에 관한 가이드를 참고하세요.

링크 업그레이드 iframe에 포함됩니다.

로그인 관련 매개변수

login_hint 쿼리 매개변수는 부가기능 웹페이지를 방문하는 클래스룸 사용자에 관한 정보를 제공합니다. 이 쿼리 매개변수는 iframe src URL에 제공됩니다. 사용자가 이전에 부가기능을 사용하여 최종 사용자 로그인 문제를 줄인 적이 있는 경우 전송됩니다. 부가기능 구현에서 이 쿼리 매개변수를 처리해야 합니다.

로그인 힌트

login_hint는 사용자의 Google 계정의 고유 식별자입니다.

계정을 탭합니다. 사용자가 부가기능에 처음 로그인한 후에는 동일한 사용자가 부가기능을 방문할 때마다 login_hint 매개변수가 전달됩니다.

login_hint 매개변수는 다음 두 가지 용도로 사용할 수 있습니다.

1. 로그인 대화상자가 표시될 때 사용자가 사용자 인증 정보를 입력하지 않아도 되도록 인증 흐름 중에 login_hint 값을 전달합니다. 사용자가 자동으로 로그인되지 않습니다.
2. 사용자가 로그인한 후 이 매개변수를 사용하여 이미 부가기능에 로그인했을 수 있는 사용자와 값을 비교합니다. 일치하는 항목을 찾으면 사용자를 로그인 상태로 두고 로그인 과정을 표시하지 않을 수 있습니다. 매개변수가 로그인한 사용자와 일치하지 않으면 사용자에게 Google 브랜드 로그인 버튼으로 로그인하라는 메시지를 표시합니다.

모든 iframe에 포함됩니다.

첨부파일 검색 iframe

첨부파일 검색 시나리오 예

1. 클래스룸 부가기능이 https://example.com/addon의 첨부파일 검색 URI로 Google Workspace Marketplace에 등록됩니다.
2. 교사가 이 부가기능을 설치하고 강의 중 하나에 새 공지사항, 과제 또는 자료를 만듭니다. 예를 들면 itemId=234, itemType=courseWork, courseId=123입니다.
3. 해당 항목을 구성하는 동안 교사는 새로 설치된 부가기능을 첨부파일로 선택합니다.
4. 클래스룸에서는 src URL이 https://example.com/addon?courseId=123&itemId=234&itemType=courseWork&addOnToken=456로 설정된 iframe을 만듭니다.
   1. 교사가 iframe 내에서 작업을 수행하여 첨부파일을 선택합니다.
5. 첨부파일을 선택하면 부가기능이 postMessage를 클래스룸으로 전송하여 iframe을 닫습니다.

teacherViewUri 및 studentViewUri iframe

studentWorkReviewUri iframe

링크 업그레이드 iframe

링크 업그레이드 시나리오 예

1. 클래스룸 부가기능이 https://example.com/upgrade의 링크 업그레이드 URI로 등록됩니다. 클래스룸에서 부가기능 첨부파일로 업그레이드하려고 시도해야 하는 링크 첨부파일에 다음과 같은 호스트 및 경로 접두사 패턴을 제공했습니다.
   • 호스트는 example.com이고 경로 접두사는 /quiz입니다.
2. 교사가 강의 중 하나에서 새 공지사항, 과제 또는 자료를 만듭니다. 예를 들면 itemId=234, itemType=courseWork, courseId=123입니다.
3. 교사가 제공한 URL 패턴과 일치하는 링크(https://example.com/quiz/5678)를 첨부파일 링크 대화상자에 붙여넣습니다. 그러면 교사에게 링크를 부가기능 첨부파일로 업그레이드하라는 메시지가 표시됩니다.

4. 클래스룸에서 URL이 https://example.com/upgrade?courseId=123&itemId=234&itemType=courseWork&addOnToken=456&urlToUpgrade=https%3A%2F%2Fexample.com%2Fquiz%2F5678로 설정된 링크 업그레이드 iframe을 실행합니다.

5. iframe에 전달된 쿼리 매개변수를 평가하고 CreateAddOnAttachment 엔드포인트를 호출합니다. urlToUpgrade 쿼리 매개변수는 iframe으로 전달될 때 URI로 인코딩됩니다. 매개변수를 디코딩하여 원래 형식으로 가져와야 합니다. 예를 들어 JavaScript는 decodeURIComponent() 함수를 제공합니다.

6. 링크에서 부가기능 첨부파일을 만들었으면 클래스룸에 postMessage를 전송하여 iframe을 닫습니다.

iframe 닫기

페이로드 {type: 'Classroom', action: 'closeIframe'}와 함께 postMessage를 전송하여 학습 도구에서 iframe을 닫을 수 있습니다. 클래스룸은 열린 원래 URI에 해당하는 host_name+port에서만 이 postMessage를 허용합니다.

<button id="close">Send message to close iframe</button>
<script>
  document.querySelector('#close')
    .addEventListener('click', () => {
        window.parent.postMessage({
            type: 'Classroom',
            action: 'closeIframe',
        }, '*');
    });
</script>

iframe에서 iframe 닫기

postMessage 이벤트를 전송하는 페이지의 도메인+포트는 iframe을 실행하는 데 사용된 URI의 도메인+포트와 동일해야 합니다. 그러지 않으면 메시지가 무시됩니다. 해결 방법은 postMessage 이벤트를 전송하는 것 외에는 아무것도 하지 않는 원래 도메인의 페이지로 다시 리디렉션하는 것입니다.

새 탭에서 iframe 닫기

교차 도메인 보호로 인해 이 작업이 실행되지 않습니다. 해결 방법은 iframe과 새 탭 간의 통신을 직접 처리하고 iframe이 궁극적으로 닫기 postMessage 이벤트를 실행하도록 하는 것입니다. 참고로 사용자가 곧 이 방법으로 탭을 만들지 못하도록 '파트너 이름으로 열기' 하이퍼링크가 삭제됩니다.

제한사항

모든 iframe은 다음 샌드박스 속성으로 열립니다.

• allow-popups
• allow-popups-to-escape-sandbox
• allow-forms
• allow-scripts
• allow-storage-access-by-user-activation
• allow-same-origin

다음 기능 정책

• allow="microphone *"

서드 파티 쿠키 차단

서드 파티 쿠키를 차단하면 iframe에서 로그인 세션을 유지하기가 어렵습니다. 여러 브라우저에서 발생하는 쿠키 차단의 현재 상태는 https://www.cookiestatus.com을 참조하세요. 물론 이 문제는 Google 클래스룸 부가기능에만 해당하는 것이 아니며 iframe 서드 파티를 운영하는 모든 웹사이트에 영향을 미칩니다. 이미 많은 파트너가 이 문제를 경험했습니다.

일반적인 해결 방법은 다음과 같습니다.

• 새 탭을 열어 퍼스트 파티 맥락에서 쿠키를 만듭니다. 일부 브라우저는 서드 파티 맥락에서 퍼스트 파티 맥락에 생성된 쿠키에 대한 액세스 권한을 부여합니다.
• 사용자에게 서드 파티 쿠키를 허용하도록 요청합니다. 하지만 모든 사용자에게 이 방법을 적용할 수 있는 것은 아닙니다.
• 쿠키를 사용하지 않는 단일 페이지 웹 애플리케이션을 설계합니다.

향후 브라우저 버전에서는 더 많은 쿠키 제한이 적용될 예정입니다. 기능 요청을 작성하여 파트너가 수행해야 하는 작업을 줄이는 방법에 관한 의견을 Google에 전달하세요.

URL 정규 표현식을 사용하여 부가기능 검색 가능성 사용 설정

교사는 링크 첨부파일이 포함된 과제를 자주 만듭니다. 부가기능 사용을 장려하려면 부가기능에서 액세스할 수 있는 리소스의 URL과 일치하는 정규 표현식을 지정할 수 있습니다. 선생님이 정규 표현식 중 하나와 일치하는 링크를 첨부하면 닫을 수 있는 대화상자가 표시되어 부가기능을 사용해 보라고 안내합니다. 계정에 부가기능이 이미 설치된 경우에만 대화상자가 표시됩니다.

교사에게 이 동작을 제공하려면 Google 담당자에게 적절한 정규식을 제공하세요. 제공한 정규 표현식이 지나치게 광범위하거나 다른 부가기능과 충돌하는 경우 더 제한적이거나 고유하도록 수정될 수 있습니다.

그림 1. 교사가 새 과제의 링크 첨부파일을 선택합니다

그림 2. 교사가 서드 파티 소스의 링크를 붙여넣는 경우 교사가 이미 서드 파티의 클래스룸 부가기능을 설치했습니다.

그림 3. 붙여넣은 링크가 서드 파티 개발자가 지정한 정규 표현식과 일치할 때 교사에게 표시되는 대화상자입니다.

교사가 그림 3과 같이 팝업에서 '사용해 보기'를 선택하면 부가기능의 첨부파일 검색 iframe으로 리디렉션됩니다.