chrome.history

설명

chrome.history API를 사용하여 브라우저의 방문한 페이지 기록과 상호작용합니다. 브라우저 방문 기록에서 URL을 추가, 삭제, 쿼리할 수 있습니다. 방문 기록 페이지를 원하는 버전으로 재정의하려면 페이지 재정의를 참고하세요.

권한

history

사용자의 브라우저 기록과 상호작용하려면 기록 API를 사용하세요.

History API를 사용하려면 확장 프로그램 매니페스트에서 "history" 권한을 선언합니다. 예를 들면 다음과 같습니다.

{
  "name": "My extension",
  ...
  "permissions": [
    "history"
  ],
  ...
}

개념 및 사용법

전환 유형

History API는 전환 유형을 사용하여 특정 방문에서 브라우저가 특정 URL로 이동한 방식을 설명합니다. 예를 들어 사용자가 다른 페이지의 링크를 클릭하여 페이지를 방문하면 전환 유형은 '링크'입니다. 전환 유형 목록은 참조 콘텐츠를 확인하세요.

예

이 API를 사용해 보려면 chrome-extension-samples 저장소의 기록 API 예를 설치하세요.

유형

HistoryItem

기록 쿼리의 결과 하나를 캡슐화하는 객체입니다.

속성

  • id

    string

    상품의 고유 식별자입니다.

  • lastVisitTime

    number 선택사항

    이 페이지가 마지막으로 로드된 시점으로, 에포크 이후 경과된 시간을 밀리초 단위로 표시합니다.

  • title

    문자열 선택사항

    마지막으로 로드된 페이지의 제목입니다.

  • typedCount

    number 선택사항

    사용자가 주소를 입력하여 이 페이지로 이동한 횟수입니다.

  • url

    문자열 선택사항

    사용자가 이동한 URL입니다.

  • visitCount

    number 선택사항

    사용자가 이 페이지로 이동한 횟수입니다.

TransitionType

Chrome 44 이상

리퍼러에서 이 방문의 전환 유형입니다.

enum

"link"
사용자가 다른 페이지의 링크를 클릭하여 이 페이지에 도달했습니다.

"입력"
사용자가 주소 표시줄에 URL을 입력하여 이 페이지에 도달했습니다. 이는 다른 명시적 탐색 작업에도 사용됩니다.

"auto_bookmark"
사용자가 UI의 추천 항목(예: 메뉴 항목)을 통해 이 페이지에 도달했습니다.

"auto_subframe"
사용자가 이전 페이지의 프레임에서 광고를 로드하는 등 요청하지 않은 하위 프레임 탐색을 통해 이 페이지에 도달했습니다. 뒤로 및 앞으로 메뉴에 새 탐색 항목이 항상 생성되는 것은 아닙니다.

"manual_subframe"
사용자가 서브프레임에서 항목을 선택하여 이 페이지에 도달했습니다.

'생성됨'
사용자가 주소 표시줄에 입력하고 Google 추천 검색어 등 URL이 아닌 항목을 선택하여 이 페이지에 도달했습니다. 예를 들어, 일치 항목은 Google 검색결과 페이지의 URL을 가질 수 있지만 사용자에게는 'Google에서 다음 검색 ...'으로 표시될 수 있습니다. 사용자가 도착 URL을 입력하거나 확인하지 않았기 때문에 입력 탐색과는 다릅니다. 이는 키워드 탐색과도 관련이 있습니다.

"auto_toplevel"
페이지가 명령줄에서 지정되었거나 시작 페이지입니다.

"form_submit"
사용자가 양식에서 값을 작성하고 양식을 제출하여 이 페이지로 이동했습니다. 일부 양식 제출에서는 이 전환 유형을 사용하지 않습니다.

"reload"
사용자가 새로고침 버튼을 클릭하거나 주소 표시줄에서 Enter를 눌러 페이지를 새로고침했습니다. 세션 복원 및 닫은 탭 다시 열기도 이 전환 유형을 사용합니다.

"keyword"
이 페이지의 URL은 기본 검색 공급자가 아닌 대체 가능한 키워드에서 생성되었습니다.

"keyword_generated"
키워드에 대해 생성된 방문에 해당합니다.

UrlDetails

Chrome 88 이상

속성

  • url

    string

    작업의 URL입니다. history.search() 호출에서 반환된 형식이어야 합니다.

VisitItem

URL에 대한 1회의 방문을 캡슐화하는 객체입니다.

속성

  • id

    string

    해당하는 history.HistoryItem의 고유 식별자입니다.

  • isLocal

    boolean

    Chrome 115 이상

    방문이 이 기기에서 시작된 경우 true입니다. 다른 기기에서 동기화된 경우 false입니다.

  • referringVisitId

    string

    리퍼러의 방문 ID

  • transition

    TransitionType

    리퍼러에서 이 방문의 전환 유형입니다.

  • visitId

    string

    이 방문의 고유 식별자입니다.

  • visitTime

    number 선택사항

    이 방문이 발생한 시점으로, 에포크 이후 경과된 시간을 밀리초 단위로 나타냅니다.

방법

addUrl()

프로미스 
chrome.history.addUrl(
  details: UrlDetails,
  callback?: function,
)

'link'의 전환 유형을 사용하여 현재 시간의 기록에 URL을 추가합니다.

매개변수

  • 세부정보

    UrlDetails

  • 콜백

    함수 선택사항

    callback 매개변수는 다음과 같습니다. 

    ()=>void

반환 값

  • Promise<void>

    Chrome 96 이상

    프로미스는 Manifest V3 이상에서 지원되지만 콜백은 이전 버전과의 호환성을 위해 제공됩니다. 동일한 함수 호출에 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

deleteAll()

프로미스 
chrome.history.deleteAll(
  callback?: function,
)

기록에서 모든 항목을 삭제합니다.

매개변수

  • 콜백

    함수 선택사항

    callback 매개변수는 다음과 같습니다. 

    ()=>void

반환 값

  • Promise<void>

    Chrome 96 이상

    프로미스는 Manifest V3 이상에서 지원되지만 콜백은 이전 버전과의 호환성을 위해 제공됩니다. 동일한 함수 호출에 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

deleteRange()

프로미스 
chrome.history.deleteRange(
  range: object,
  callback?: function,
)

기록에서 지정된 기간 내의 모든 항목을 삭제합니다. 모든 방문이 해당 범위에 속하지 않는 한 페이지는 방문 기록에서 삭제되지 않습니다.

매개변수

  • 범위

    객체

    • endTime

      숫자

      이 날짜 이전에 기록에 추가된 항목으로, 에포크 이후 경과된 밀리초로 표시됩니다.

    • startTime

      숫자

      이 날짜 이후에 기록에 추가된 항목으로, 에포크 이후 경과된 밀리초로 표시됩니다.

  • 콜백

    함수 선택사항

    callback 매개변수는 다음과 같습니다. 

    ()=>void

반환 값

  • Promise<void>

    Chrome 96 이상

    프로미스는 Manifest V3 이상에서 지원되지만 콜백은 이전 버전과의 호환성을 위해 제공됩니다. 동일한 함수 호출에 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

deleteUrl()

프로미스 
chrome.history.deleteUrl(
  details: UrlDetails,
  callback?: function,
)

기록에서 지정된 URL과 일치하는 항목을 모두 삭제합니다.

매개변수

  • 세부정보

    UrlDetails

  • 콜백

    함수 선택사항

    callback 매개변수는 다음과 같습니다. 

    ()=>void

반환 값

  • Promise<void>

    Chrome 96 이상

    프로미스는 Manifest V3 이상에서 지원되지만 콜백은 이전 버전과의 호환성을 위해 제공됩니다. 동일한 함수 호출에 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

getVisits()

프로미스 
chrome.history.getVisits(
  details: UrlDetails,
  callback?: function,
)

URL 방문에 대한 정보를 검색합니다.

매개변수

  • 세부정보

    UrlDetails

  • 콜백

    함수 선택사항

    callback 매개변수는 다음과 같습니다. 

    (results: VisitItem[])=>void

반환 값

  • Promise<VisitItem[]>

    Chrome 96 이상

    프로미스는 Manifest V3 이상에서 지원되지만 콜백은 이전 버전과의 호환성을 위해 제공됩니다. 동일한 함수 호출에 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

프로미스 
chrome.history.search(
  query: object,
  callback?: function,
)

검색어와 일치하는 각 페이지의 마지막 방문 기록을 검색합니다.

매개변수

  • query

    객체

    • endTime

      number 선택사항

      이 날짜 이전에 방문한 것으로 결과를 제한하며 에포크 이후 밀리초 단위로 표시됩니다.

    • maxResults

      number 선택사항

      검색할 최대 결과 수입니다. 기본값은 100입니다.

    • startTime

      number 선택사항

      이 날짜 이후에 방문한 항목으로 결과를 제한하며 해당 에포크 이후 밀리초 단위로 표시됩니다. 속성을 지정하지 않으면 기본적으로 24시간으로 설정됩니다.

    • text

      string

      기록 서비스에 대한 자유 텍스트 쿼리입니다. 모든 페이지를 검색하려면 이 입력란을 비워두세요.

  • 콜백

    함수 선택사항

    callback 매개변수는 다음과 같습니다. 

    (results: HistoryItem[])=>void

반환 값

  • Promise<HistoryItem[]>

    Chrome 96 이상

    프로미스는 Manifest V3 이상에서 지원되지만 콜백은 이전 버전과의 호환성을 위해 제공됩니다. 동일한 함수 호출에 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

이벤트

onVisited

chrome.history.onVisited.addListener(
  callback: function,
)

URL을 방문하면 시작되어 해당 URL의 HistoryItem 데이터를 제공합니다. 이 이벤트는 페이지가 로드되기 전에 실행됩니다.

매개변수

  • 콜백

    기능

    callback 매개변수는 다음과 같습니다. 

    (result: HistoryItem)=>void

onVisitRemoved

chrome.history.onVisitRemoved.addListener(
  callback: function,
)

기록에서 URL이 하나 이상 삭제되면 실행됩니다. 모든 방문이 삭제되면 URL이 기록에서 삭제됩니다.

매개변수

  • 콜백

    기능

    callback 매개변수는 다음과 같습니다. 

    (removed: object)=>void

    • 삭제됨

      객체

      • allHistory

        boolean

        모든 기록이 삭제된 경우 true입니다. true인 경우 URL이 비어 있게 됩니다.

      • urls

        string[] 선택사항