Analytics


PSPDFKit Analytics API allows you to easly collect usage data based on user's activity taking place in PSPDFKit components.

PSPDFKit Analytics API consists of:

Integration

Enable analytics

PSPDFKit Analytics are disabled by default, so first you need to enable it:

Copy
1
PSPDFKit.sharedInstance.analytics.enabled = true
Copy
1
PSPDFKit.sharedInstance.analytics.enabled = YES;

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

Be aware that events are delivered on a background queue.

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

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

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

Events

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 PSPDFAnalyticsEvents.h header and in the list below.

  • PSPDFAnalyticsEventNameDocumentLoad (Raw value: pspdf_load_document)

    This event signifies that the user has loaded a document.

    No attributes.

  • PSPDFAnalyticsEventNamePageChange (Raw value: pspdf_change_page)

    This signifies that the user changed the page.

    No attributes.

  • PSPDFAnalyticsEventNameAnnotationCreationModeEnter (Raw value: pspdf_enter_annotation_creation_mode)

    This event signifies that the user opened the annotation toolbar.

    No attributes.

  • PSPDFAnalyticsEventNameAnnotationCreationModeExit (Raw value: pspdf_exit_annotation_creation_mode)

    This event signifies that the user closed the annotation toolbar.

    No attributes.

  • PSPDFAnalyticsEventNameAnnotationCreatorDialogShow (Raw value: pspdf_show_annotation_creator_dialog)

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

    No attributes.

  • PSPDFAnalyticsEventNameAnnotationCreatorDialogCancel (Raw value: pspdf_cancel_annotation_creator_dialog)

    Signifies that the annotation creator dialog was cancelled by the user.

    No attributes.

  • PSPDFAnalyticsEventNameAnnotationCreatorSet (Raw value: pspdf_set_annotation_creator)

    Signifies that the annotation creator dialog was confirmed by the user, setting a creator name.

    No attributes.

  • PSPDFAnalyticsEventNameAnnotationSelect (Raw value: pspdf_select_annotation)

    This signifies that the user selected an annotation, either by tapping it or by any other option (for example using the annotation list).

    Attributes:

    • Key: PSPDFAnalyticsEventAttributeNameAnnotationType. Value: PSPDFAnnotationString of the selected annotation.
  • PSPDFAnalyticsEventNameAnnotationCreate (Raw value: pspdf_create_annotation)

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

    Attributes:

    • Key: PSPDFAnalyticsEventAttributeNameAnnotationType. Value: PSPDFAnnotationString of the created annotation.
  • PSPDFAnalyticsEventNameAnnotationDelete (Raw value: pspdf_delete_annotation)

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

    Attributes:

    • Key: PSPDFAnalyticsEventAttributeNameAnnotationType. Value: PSPDFAnnotationString of the deleted annotation.
  • PSPDFAnalyticsEventNameAnnotationInspectorShow (Raw value: pspdf_show_annotation_inspector)

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

    No attributes.

  • PSPDFAnalyticsEventNameTextSelect (Raw value: pspdf_select_text)

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

    No attributes.

  • PSPDFAnalyticsEventNameOutlineOpen (Raw value: pspdf_open_outline_view)

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

    No attributes.

  • PSPDFAnalyticsEventNameOutlineElementSelect (Raw value: pspdf_tap_outline_element_in_outline_list)

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

    No attributes.

  • PSPDFAnalyticsEventNameOutlineAnnotationSelect (Raw value: pspdf_tap_annotation_in_outline_list)

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

    Attributes:

    • Key: PSPDFAnalyticsEventAttributeNameAnnotationType. Value: PSPDFAnnotationString of the selected annotation.
  • PSPDFAnalyticsEventNameThumbnailGridOpen (Raw value: pspdf_open_thumbnail_grid)

    This signifies that the user opened the thumbnail grid view.

    No attributes.

  • PSPDFAnalyticsEventNameDocumentEditorOpen (Raw value: pspdf_open_document_editor)

    This signifies that the user opened the document editor.

    No attributes.

  • PSPDFAnalyticsEventNameDocumentEditorAction (Raw value: pspdf_perform_document_editor_action)

    This signifies that the user performed an action inside the document editor.

    Attributes:

    • Key: PSPDFAnalyticsEventAttributeNameAction. Value: PSPDFAnalyticsEventAttributeValueAction the user performed in the document editor (like PSPDFAnalyticsEventAttributeValueActionInsertNewPage)
  • PSPDFAnalyticsEventNameBookmarkAdd (Raw value: pspdf_add_bookmark)

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

    No attributes.

  • PSPDFAnalyticsEventNameBookmarkEdit (Raw value: pspdf_edit_bookmarks)

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

    No attributes.

  • PSPDFAnalyticsEventNameBookmarkRemove (Raw value: pspdf_remove_bookmark)

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

    No attributes.

  • PSPDFAnalyticsEventNameBookmarkSort (Raw value: pspdf_sort_bookmark)

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

    No attributes.

  • PSPDFAnalyticsEventNameBookmarkRename (Raw value: pspdf_rename_bookmark)

    This signifies that the user renamed a bookmark.

    No attributes.

  • PSPDFAnalyticsEventNameBookmarkSelect (Raw value: pspdf_tap_bookmark_in_bookmark_list)

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

    No attributes.

  • PSPDFAnalyticsEventNameSearchStart (Raw value: pspdf_start_search)

    This signifies that the user started a search in the document by pressing the search icon (or any other way).

    No attributes.

  • PSPDFAnalyticsEventNameSearchResultSelect (Raw value: pspdf_select_search_result)

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

  • PSPDFAnalyticsEventNameShare (Raw value: pspdf_share)

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

    Attributes:

    • Key: PSPDFAnalyticsEventAttributeNameActivityType. Value: Activity type the user selected as string.
  • PSPDFAnalyticsEventNameToolbarMove (Raw value: pspdf_move_toolbar)

    This signifies that the toolbar was moved to a different location.

    Attributes:

    • Key: PSPDFAnalyticsEventAttributeValueToolbarPosition. Value: PSPDFFlexibleToolbarPosition of the destination.

Custom events

PSPDFKit events pipeline can also be used to deliver your own custom events.

Extend PSPDFAnalyticsEventName type with your custom events:

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

And use PSPDFAnalytics object to deliver them:

Copy
1
PSPDFKit.sharedInstance.analytics.logEvent(.someCustomAction)
Copy
1
[PSPDFKit.sharedInstance.analytics logEvent:PSPDFAnalyticsEventNameSomeCustomAction];

The event will be dispatched to all registered PSPDFAnalyticsClient instances.

Was this page helpful? We're happy to answer any questions.