Analytics

The PSPDFKit Analytics API allows you to easily collect usage data based on a user’s activity taking place in PSPDFKit components.

The PSPDFKit Analytics API consists of:

  • A PDFAnalytics object that you can access through a shared PSPDFKit instance
  • A PDFAnalyticsClient protocol that you need to implement to capture analytics events

Integration

Enable Analytics

The PSPDFKit Analytics API is disabled by default, so you first need to enable it to use it:

1
PSPDFKit.SDK.shared.analytics.enabled = true
1
PSPDFKitGlobal.sharedInstance.analytics.enabled = YES;

Next you need to implement the PDFAnalyticsClient protocol. Your PDFAnalyticsClient is a place to process PSPDFKit events and pass them to the analytics service of your choice.

Be aware that events are delivered on a background queue.

Create an instance of your PDFAnalyticsClient when the app launches (preferably at the same time you’re configuring the PSPDFKit license) and register it with PDFAnalytics:

1
2
let analyticsClient = YourAnalyticsClient()
PSPDFKit.SDK.shared.analytics.add(analyticsClient)
Copy
1
2
id<PSPDFAnalyticsClient> analyticsClient = [[YourAnalyticsClient alloc] init];
[PSPDFKitGlobal.sharedInstance.analytics addAnalyticsClient:analyticsClient];

You can find a simple PDFAnalyticsClient implementation in AnalyticsClientExample.swift in the PSPDFKit Catalog app.

Events

An event has a name and a dictionary of additional parameters. Event parameters are of standard, JSON-friendly types.

All PSPDFKit event names are prefixed with pspdf_ and use underscore_case.

You can find the complete list of PSPDFKit events and parameters in the PSPDFAnalyticsEvents.h header and in the list below.

  • PDFAnalytics.EventName.documentLoad (raw value: pspdf_load_document)

    This signifies that the user has loaded a document.

    No attributes.

  • PDFAnalytics.EventName.spreadChange (raw value: pspdf_change_spread)

    This signifies that spread was changed.

    No attributes.

  • PDFAnalytics.EventName.annotationCreationModeEnter (raw value: pspdf_enter_annotation_creation_mode)

    This signifies that the user opened the annotation toolbar.

    No attributes.

  • PDFAnalytics.EventName.annotationCreationModeExit (raw value: pspdf_exit_annotation_creation_mode)

    This signifies that the user closed the annotation toolbar.

    No attributes.

  • PDFAnalytics.EventName.annotationCreatorDialogShow (raw value: pspdf_show_annotation_creator_dialog)

    This signifies that the annotation creator dialog was shown to the user.

    No attributes.

  • PDFAnalytics.EventName.annotationCreatorDialogCancel (raw value: pspdf_cancel_annotation_creator_dialog)

    This signifies that the annotation creator dialog was canceled by the user.

    No attributes.

  • PDFAnalytics.EventName.annotationCreatorSet (raw value: pspdf_set_annotation_creator)

    This signifies that the annotation creator dialog was confirmed by the user, thereby setting a creator name.

    No attributes.

  • PDFAnalytics.EventName.annotationSelect (raw value: pspdf_select_annotation)

    This signifies that the user selected an annotation, e.g. by tapping it.

    Attributes:

    • Key: PDFAnalytics.EventAttributeName.anotationType. Value: Annotation.Tool of the selected annotation.
  • PDFAnalytics.EventName.annotationCreate (raw value: pspdf_create_annotation)

    This signifies that the user created an annotation and added it to the document.

    Attributes:

    • Key: PDFAnalytics.EventAttributeName.anotationType. Value: Annotation.Tool of the created annotation.
  • PDFAnalytics.EventName.annotationDelete (raw value: pspdf_delete_annotation)

    This signifies that the user deleted an annotation from the document.

    Attributes:

    • Key: PDFAnalytics.EventAttributeName.annotationType. Value: Annotation.Tool of the deleted annotation.
  • PDFAnalytics.EventName.annotationInspectorShow (raw value: pspdf_show_annotation_inspector)

    This signifies that the user opened the annotation inspector for editing annotation properties, either via the annotation toolbar or by editing an existing annotation.

    No attributes.

  • PDFAnalytics.EventName.textSelect (raw value: pspdf_select_text)

    This signifies that the user has selected text on the document.

    No attributes.

  • PDFAnalytics.EventName.outlineOpen (raw value: pspdf_open_outline_view)

    This signifies that the user opened the outline containing the document outline, annotations, and bookmarks.

    No attributes.

  • PDFAnalytics.EventName.outlineElementSelect (raw value: pspdf_tap_outline_element_in_outline_list)

    This signifies that the user tapped an outline element in the outline view.

    No attributes.

  • PDFAnalytics.EventName.outlineAnnotationSelect (raw value: pspdf_tap_annotation_in_outline_list)

    This signifies that the user tapped an annotation in the outline view.

    Attributes:

    • Key: PDFAnalytics.EventAttributeName.annotationType. Value: Annotation.Tool of the selected annotation.
  • PDFAnalytics.EventName.thumbnailGridOpen (raw value: pspdf_open_thumbnail_grid)

    This signifies that the user opened the thumbnail grid view.

    No attributes.

  • PDFAnalytics.EventName.documentEditorOpen (raw value: pspdf_open_document_editor)

    This signifies that the user opened the Document Editor.

    No attributes.

  • PDFAnalytics.EventName.documentEditorAction (raw value: pspdf_perform_document_editor_action)

    This signifies that the user performed an action inside the Document Editor.

    Attributes:

    • Key: PDFAnalytics.EventAttributeName.action. Value: One of the PDFAnalytics.EventAttributeValue.action..s that was performed by the user. For example, PDFAnalytics.EventAttributeValue.actionInsertNewPage.
  • PDFAnalytics.EventName.bookmarkAdd (raw value: pspdf_add_bookmark)

    This signifies that the user added a bookmark to the document.

    No attributes.

  • PDFAnalytics.EventName.bookmarkEdit (raw value: pspdf_edit_bookmarks)

    This signifies that the user has entered bookmark-editing mode inside the bookmark list.

    No attributes.

  • PDFAnalytics.EventName.bookmarkRemove (raw value: pspdf_remove_bookmark)

    This signifies that the user has deleted a bookmark from the document.

    No attributes.

  • PDFAnalytics.EventName.bookmarkSort (raw value: pspdf_sort_bookmark)

    This signifies that the user changed the order of a bookmark item in the bookmark list.

    No attributes.

  • PDFAnalytics.EventName.bookmarkRename (raw value: pspdf_rename_bookmark)

    This signifies that the user renamed a bookmark.

    No attributes.

  • PDFAnalytics.EventName.bookmarkSelect (raw value: pspdf_tap_bookmark_in_bookmark_list)

    This signifies that the user tapped a bookmark in the bookmark list.

    No attributes.

  • PDFAnalytics.EventName.searchStart (raw value: pspdf_start_search)

    This signifies that the user started a search in the document e.g. by pressing the search icon.

    No attributes.

  • PDFAnalytics.EventName.searchResultSelect (raw value: pspdf_select_search_result)

    This signifies that the user selected a search result after searching the document.

    No attributes.

  • PDFAnalytics.EventName.share (raw value: pspdf_share)

    This signifies that the user shared the document using the share sheet.

    Attributes:

    • Key: PDFAnalytics.EventAttributeName.activityType. Value: Activity type the user selected as string.
  • PDFAnalytics.EventName.toolbarMove (raw value: pspdf_move_toolbar): This signifies that the toolbar was moved to a different location. Attributes:

    1
    2
    
    	- Key: `PDFAnalytics.EventAttributeValue.toolbarPosition`.
    	- Value: `FlexibleToolbar.Position` of the destination.
    

Custom Events

The PSPDFKit events pipeline can also be used to deliver custom events.

Extend the PDFAnalytics.EventName type with your custom events:

1
2
3
extension PDFAnalyticsEventName {
    static var someCustomAction = PDFAnalyticsEventName(rawValue: "some_custom_action")
}
Copy
1
2
PSPDF_EXPORT PSPDFAnalyticsEventName const PSPDFAnalyticsEventNameSomeCustomAction; // in *.h
PSPDFAnalyticsEventName const PSPDFAnalyticsEventNameSomeCustomAction = @"some_custom_action"; // in *.m

Then use the PDFAnalytics object to deliver them:

1
PSPDFKit.SDK.shared.analytics.logEvent(.someCustomAction)
1
[PSPDFKitGlobal.sharedInstance.analytics logEvent:PSPDFAnalyticsEventNameSomeCustomAction];

The event in the above example will be dispatched to all registered PDFAnalyticsClient instances.